Desktop app (Windows)
The Ascendly desktop app is an Electron client for employees (access level 1). It shares the same API and much of the web UI (@web/* imports) but focuses on read-only scorecard snapshots, My ATW requests, notifications, and profile — not manager entry CRUD.
Status (June 2026): Phase 2 shipped (BSC Home, notifications, My ATW, tray, offline). Phase 3 in progress — NSIS installer + auto-update (Progress report).
Install and sign-in
- Build or install the Windows package (
desktop/—npm run build:winwhen ready). - Set
VITE_API_BASE_URLandVITE_GOOGLE_CLIENT_ID(same OAuth client as web, plus loopback redirecthttp://127.0.0.1:46852/auth/callback). - Continue with Google opens the system browser; JWT + refresh token are stored in OS-encrypted storage. Silent renewal via
POST /v1/auth/refresh; sign-out revokes the refresh token.
Routes
| Route | Purpose |
|---|---|
/bsc | Home — My score this month, eval status, ATW points, issues |
/my-atw | Submit or cancel ATW entry requests (with proof upload) |
/notifications | Full notification inbox |
/settings/* | Notifications prefs, appearance, profile shortcuts |
/profile | Profile (via titlebar avatar) |
Primary nav: BSC, My ATW. Managers who need scorecard entry pages or the recycle bin should use web.
BSC Home (live snapshot)
Home cards poll the API every 15 seconds and refetch when you focus the window or open Home. Data sources:
| Card | API |
|---|---|
| My score this month | GET /v1/dashboard/bsc (self view) |
| ATW points | GET /v1/scorecard/atw-entries/export |
| Eval status | GET /v1/scorecard/missing-excess-evals |
| Issues | Attendance / productivity / incidents exports |
Self-view BSC KPIs are computed from live Mongo on the server (not a stale BigQuery snapshot). After a manager deletes an ATW entry, both ATW points and BSC ATW % should update on Home within seconds (plus notification-driven refetch).
See Dashboard overview § Balanced Scorecard and BigQuery dashboard § Read path.
Notifications
- Titlebar bell with unread badge (badge stays inside the button so it is not clipped by the frameless shell).
- Toasts for new unread items; optional native Windows toast.
- Poll interval: 15s foreground / 10s background.
- Any scorecard.* notification triggers Home query refresh (+ follow-up at +3s for aggregate sync lag).
Full behavior: Notifications.
System tray & activity
| Behavior | Detail |
|---|---|
| Close (×) | Minimizes to tray — app keeps running |
| Tray left-click | Restore/focus main window |
| Tray right-click | Open · Sign out · Quit |
| Activity heartbeat | POST /v1/auth/activity-heartbeat with client: "desktop" while the window is visible on screen (not minimized, not tray-hidden) |
| Home banner | Shows desktop active minutes (today + 7-day rolling) |
See User activity for full monitoring rules (web vs desktop, last active, troubleshooting).
Legal links (Privacy, Terms) open in the system browser.
Offline & connectivity
DesktopConnectivityBanner surfaces:
- Network unreachable — Retry button; health poll every 30s
- Session expired — Sign in again (refresh token invalid or revoked)
API failures are reported through shared apiConnectivity.ts.
What stays on web
| Capability | Client |
|---|---|
| Scorecard entry create/edit/delete | Web |
| Recycle bin (restore / purge) | Web |
| BSC manager dashboards (team scope, bonus matrix, finalize, comparison) | Web |
| System admin | Web |
Local development
bash
cd api && ./dev.sh # API on :8000
cd desktop && npm run dev # Renderer on :5175Use npm run dev:watch when changing main process, preload, or IPC.
Related docs
- Notifications — types, admin config, web parity
- User activity — last active, active minutes, visibility rules
- Platform & admin — employee list, impersonation
- Scorecard § ATW — manager ATW entries vs employee requests
- Progress report — desktop milestone status