# potlakai/nus-desktop architecture

> Architecture diagram of the GitHub repository potlakai/nus-desktop, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/potlakai/nus-desktop
- Repository: https://github.com/potlakai/nus-desktop

## Overview

Nūs Desktop is a local-first semester organizer: students import course material, review AI-proposed work, and manage tasks and deadlines from a local database. Its Electron main process coordinates the dashboard, AI and integrations; a persistent Companion overlay adds voice and guided, screen-aware help. The README also documents account plans, Stripe billing, and anonymous usage metrics. Edges follow shown imports/calls or README-described behavior; several feature implementations were not sampled, so uncertain wiring is omitted.

Main entry points: [`src/main.js`](https://github.com/potlakai/nus-desktop/blob/main/src/main.js) (Desktop runtime), [`companion/index.js`](https://github.com/potlakai/nus-desktop/blob/main/companion/index.js) (Companion runtime), [`companion/src/guide/session.js`](https://github.com/potlakai/nus-desktop/blob/main/companion/src/guide/session.js) (Guide session), [`renderer/app.js`](https://github.com/potlakai/nus-desktop/blob/main/renderer/app.js) (Dashboard UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop organizer"]
  node_dashboard["Dashboard UI<br/>[app.js]"]
  node_desktop_runtime["Desktop runtime<br/>[main.js]"]
  node_semester_store[("Semester database<br/>[db.js]")]
  node_syllabus_ai["Syllabus and AI<br/>[ai.js]"]
  node_task_logic["Task planning<br/>[logic.js]"]
  node_smart_tasks["Smart tasks<br/>[smart.js]"]
  node_email_drafts["Email drafts<br/>[draft.js]"]
  node_local_voice["Local transcription<br/>[stt-local.js]"]
end

subgraph group_companion["Companion overlay"]
  node_companion_runtime["Companion runtime<br/>[index.js]"]
  node_companion_ui["Knot interface<br/>[renderer.js]"]
  node_companion_store[("Companion settings<br/>[store.js]")]
  node_companion_speech["Companion speech<br/>[stt.js]"]
  node_companion_ai["Companion AI<br/>[llm.js]"]
  node_guide_session["Guide session<br/>[session.js]"]
  node_guide_pointing["Target selection<br/>[pointing.js]"]
  node_guide_verification["Target verification<br/>[verify.js]"]
  node_screen_probe["Windows UI probe<br/>[probe.js]"]
end

subgraph group_integrations["External integrations"]
  node_calendar["Google Calendar<br/>[gcal.js]"]
  node_outlook["Outlook inbox<br/>[outlook.js]"]
end

subgraph group_services["Account and metrics"]
  node_usage_limits["Plan limits<br/>[limits.js]"]
  node_account_auth["Account auth<br/>[auth.js]"]
  node_usage_stats["Usage metrics<br/>[stats.js]"]
  node_supabase_checkout["Checkout endpoint<br/>[index.ts]"]
end

node_student(("Student"))
node_stripe["Stripe"]
node_supabase["Supabase"]
node_anthropic["Anthropic Claude"]
node_gemini["Google Gemini"]

node_student -->|"uses"| node_dashboard
node_dashboard -.->|"requests actions"| node_desktop_runtime
node_desktop_runtime -->|"reads and writes"| node_semester_store
node_desktop_runtime -->|"extracts syllabus"| node_syllabus_ai
node_desktop_runtime -->|"decomposes tasks"| node_task_logic
node_desktop_runtime -->|"uses"| node_smart_tasks
node_desktop_runtime -->|"uses"| node_calendar
node_desktop_runtime -->|"uses"| node_outlook
node_desktop_runtime -->|"uses"| node_email_drafts
node_desktop_runtime -->|"transcribes locally"| node_local_voice
node_student -->|"asks or speaks"| node_companion_ui
node_desktop_runtime -->|"hosts overlay"| node_companion_runtime
node_companion_runtime -.->|"sends UI events"| node_companion_ui
node_companion_runtime -->|"reads settings"| node_companion_store
node_companion_runtime -->|"transcribes audio"| node_companion_speech
node_companion_runtime -->|"requests answers"| node_companion_ai
node_companion_runtime -->|"starts guides"| node_guide_session
node_guide_session -->|"selects target"| node_guide_pointing
node_guide_session -->|"validates target"| node_guide_verification
node_guide_session -->|"queries controls"| node_screen_probe
node_companion_ai -->|"calls provider"| node_gemini
node_desktop_runtime -->|"calls provider"| node_anthropic
node_desktop_runtime -.->|"checks caps"| node_usage_limits
node_desktop_runtime -.->|"checks account"| node_account_auth
node_account_auth -->|"authenticates"| node_supabase
node_desktop_runtime -.->|"records usage"| node_usage_stats
node_desktop_runtime -->|"starts Pro checkout"| node_supabase_checkout
node_supabase_checkout -->|"creates checkout"| node_stripe

click node_dashboard "https://github.com/potlakai/nus-desktop/blob/main/renderer/app.js"
click node_desktop_runtime "https://github.com/potlakai/nus-desktop/blob/main/src/main.js"
click node_semester_store "https://github.com/potlakai/nus-desktop/blob/main/src/db.js"
click node_syllabus_ai "https://github.com/potlakai/nus-desktop/blob/main/src/ai.js"
click node_task_logic "https://github.com/potlakai/nus-desktop/blob/main/src/logic.js"
click node_smart_tasks "https://github.com/potlakai/nus-desktop/blob/main/src/smart.js"
click node_calendar "https://github.com/potlakai/nus-desktop/blob/main/src/gcal.js"
click node_outlook "https://github.com/potlakai/nus-desktop/blob/main/src/outlook.js"
click node_email_drafts "https://github.com/potlakai/nus-desktop/blob/main/src/draft.js"
click node_local_voice "https://github.com/potlakai/nus-desktop/blob/main/src/stt-local.js"
click node_companion_runtime "https://github.com/potlakai/nus-desktop/blob/main/companion/index.js"
click node_companion_ui "https://github.com/potlakai/nus-desktop/blob/main/companion/renderer/renderer.js"
click node_companion_store "https://github.com/potlakai/nus-desktop/blob/main/companion/src/store.js"
click node_companion_speech "https://github.com/potlakai/nus-desktop/blob/main/companion/src/stt.js"
click node_companion_ai "https://github.com/potlakai/nus-desktop/blob/main/companion/src/llm.js"
click node_guide_session "https://github.com/potlakai/nus-desktop/blob/main/companion/src/guide/session.js"
click node_guide_pointing "https://github.com/potlakai/nus-desktop/blob/main/companion/src/guide/pointing.js"
click node_guide_verification "https://github.com/potlakai/nus-desktop/blob/main/companion/src/guide/verify.js"
click node_screen_probe "https://github.com/potlakai/nus-desktop/blob/main/companion/src/win/probe.js"
click node_usage_limits "https://github.com/potlakai/nus-desktop/blob/main/src/limits.js"
click node_account_auth "https://github.com/potlakai/nus-desktop/blob/main/src/auth.js"
click node_usage_stats "https://github.com/potlakai/nus-desktop/blob/main/src/stats.js"
click node_supabase_checkout "https://github.com/potlakai/nus-desktop/blob/main/supabase/functions/create-checkout/index.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_dashboard,node_desktop_runtime,node_semester_store,node_syllabus_ai,node_task_logic,node_smart_tasks,node_email_drafts,node_local_voice toneBlue
class node_companion_runtime,node_companion_ui,node_companion_store,node_companion_speech,node_companion_ai,node_guide_session,node_guide_pointing,node_guide_verification,node_screen_probe toneAmber
class node_calendar,node_outlook toneMint
class node_usage_limits,node_account_auth,node_usage_stats,node_supabase_checkout toneRose
class node_student,node_stripe,node_supabase,node_anthropic,node_gemini toneIndigo
```

## Components

### Desktop organizer

- [Dashboard UI](https://github.com/potlakai/nus-desktop/blob/main/renderer/app.js): `renderer/app.js`
- [Desktop runtime](https://github.com/potlakai/nus-desktop/blob/main/src/main.js): `src/main.js`
- [Semester database](https://github.com/potlakai/nus-desktop/blob/main/src/db.js): `src/db.js`
- [Syllabus and AI](https://github.com/potlakai/nus-desktop/blob/main/src/ai.js): `src/ai.js`
- [Task planning](https://github.com/potlakai/nus-desktop/blob/main/src/logic.js): `src/logic.js`
- [Smart tasks](https://github.com/potlakai/nus-desktop/blob/main/src/smart.js): `src/smart.js`
- [Email drafts](https://github.com/potlakai/nus-desktop/blob/main/src/draft.js): `src/draft.js`
- [Local transcription](https://github.com/potlakai/nus-desktop/blob/main/src/stt-local.js): `src/stt-local.js`

### Companion overlay

- [Companion runtime](https://github.com/potlakai/nus-desktop/blob/main/companion/index.js): `companion/index.js`
- [Knot interface](https://github.com/potlakai/nus-desktop/blob/main/companion/renderer/renderer.js): `companion/renderer/renderer.js`
- [Companion settings](https://github.com/potlakai/nus-desktop/blob/main/companion/src/store.js): `companion/src/store.js`
- [Companion speech](https://github.com/potlakai/nus-desktop/blob/main/companion/src/stt.js): `companion/src/stt.js`
- [Companion AI](https://github.com/potlakai/nus-desktop/blob/main/companion/src/llm.js): `companion/src/llm.js`
- [Guide session](https://github.com/potlakai/nus-desktop/blob/main/companion/src/guide/session.js): `companion/src/guide/session.js`
- [Target selection](https://github.com/potlakai/nus-desktop/blob/main/companion/src/guide/pointing.js): `companion/src/guide/pointing.js`
- [Target verification](https://github.com/potlakai/nus-desktop/blob/main/companion/src/guide/verify.js): `companion/src/guide/verify.js`
- [Windows UI probe](https://github.com/potlakai/nus-desktop/blob/main/companion/src/win/probe.js): `companion/src/win/probe.js`

### External integrations

- [Google Calendar](https://github.com/potlakai/nus-desktop/blob/main/src/gcal.js): `src/gcal.js`
- [Outlook inbox](https://github.com/potlakai/nus-desktop/blob/main/src/outlook.js): `src/outlook.js`

### Account and metrics

- [Plan limits](https://github.com/potlakai/nus-desktop/blob/main/src/limits.js): `src/limits.js`
- [Account auth](https://github.com/potlakai/nus-desktop/blob/main/src/auth.js): `src/auth.js`
- [Usage metrics](https://github.com/potlakai/nus-desktop/blob/main/src/stats.js): `src/stats.js`
- [Checkout endpoint](https://github.com/potlakai/nus-desktop/blob/main/supabase/functions/create-checkout/index.ts): `supabase/functions/create-checkout/index.ts`

### Other components

- **Student**
- **Stripe**
- **Supabase**
- **Anthropic Claude**
- **Google Gemini**

## Connections

- Student → Dashboard UI: uses
- Dashboard UI → Desktop runtime: requests actions
- Desktop runtime → Semester database: reads and writes (evidence: `src/main.js`)
- Desktop runtime → Syllabus and AI: extracts syllabus (evidence: `src/main.js`)
- Desktop runtime → Task planning: decomposes tasks (evidence: `src/main.js`)
- Desktop runtime → Smart tasks: uses (evidence: `src/main.js`)
- Desktop runtime → Google Calendar: uses (evidence: `src/main.js`)
- Desktop runtime → Outlook inbox: uses (evidence: `src/main.js`)
- Desktop runtime → Email drafts: uses (evidence: `src/main.js`)
- Desktop runtime → Local transcription: transcribes locally (evidence: `src/main.js`)
- Student → Knot interface: asks or speaks
- Desktop runtime → Companion runtime: hosts overlay (evidence: `src/main.js`)
- Companion runtime → Knot interface: sends UI events
- Companion runtime → Companion settings: reads settings (evidence: `companion/index.js`)
- Companion runtime → Companion speech: transcribes audio (evidence: `companion/index.js`)
- Companion runtime → Companion AI: requests answers (evidence: `companion/index.js`)
- Companion runtime → Guide session: starts guides (evidence: `companion/index.js`)
- Guide session → Target selection: selects target (evidence: `companion/src/guide/session.js`)
- Guide session → Target verification: validates target (evidence: `companion/src/guide/session.js`)
- Guide session → Windows UI probe: queries controls (evidence: `companion/src/guide/session.js`)
- Companion AI → Google Gemini: calls provider
- Desktop runtime → Anthropic Claude: calls provider
- Desktop runtime → Plan limits: checks caps (evidence: `src/main.js`)
- Desktop runtime → Account auth: checks account (evidence: `src/main.js`)
- Account auth → Supabase: authenticates (evidence: `src/auth.js`)
- Desktop runtime → Usage metrics: records usage (evidence: `src/main.js`)
- Desktop runtime → Checkout endpoint: starts Pro checkout
- Checkout endpoint → Stripe: creates checkout (evidence: `supabase/functions/create-checkout/index.ts`)
