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, Weekly Kudos, and profile — not manager entry CRUD.
In the product today: BSC Home, notifications, My ATW, Weekly Kudos sticky widget, system tray, offline banner, activity heartbeat, Windows installer packaging, and auto-update (About / tray when an update is ready).
Install and sign-in
- Install the Windows package built from
desktop/(npm run build:win→ NSIS installer), or run from a distributed build. - 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; a 7-day access token plus a 365-day refresh token are stored in OS-encrypted storage. Silent renewal via
POST /v1/auth/refresh; sign-out revokes the refresh token. Web sessions are 7 days with no refresh — see Platform & admin § Session length.
Updates: electron-updater can download updates; About checks for updates, and the tray can offer Restart to update when a restart is required. Staging/production channel switching (if configured) is also on About.
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 | Delivery preferences |
/settings/appearance | Theme, launch at Windows startup, Weekly Kudos fade / opacity |
/settings/profile | Profile shortcuts |
/settings/permissions | Permissions matrix (level 5) |
/settings/about | Version, update check, environment channel |
#/kudos-widget | Sticky Weekly Kudos window (outside main shell) |
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.
Weekly Kudos widget
Published recognition cards for the signed-in employee open in a second always-on-top window. Polls GET /v1/scorecard/weekly-kudos/me. Tray: Bring Weekly Kudos to front / Send Weekly Kudos back. Full behavior: Weekly Kudos.
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 · Bring/Send Weekly Kudos · Restart to update (when pending) · 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, revoked, or past 365 days)
API failures are reported through shared apiConnectivity.ts.
What stays on web
| Capability | Client |
|---|---|
| Scorecard entry create/edit/delete | Web |
| Weekly Kudos authoring / publish | Web |
| Recycle bin (restore / purge) | Web |
| BSC manager dashboards (team scope, bonus matrix, finalize, comparison) | Web |
| News, Learning authoring, 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
- Weekly Kudos — designer + widget
- 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
- What's in Ascendly — product map