# vpwillwreckyou/momentum architecture

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

- Interactive diagram: https://gitdiagram.com/vpwillwreckyou/momentum
- Repository: https://github.com/vpwillwreckyou/momentum

## Overview

MOMENTUM is a local-first goal-planning application: users organize goals, tasks, milestones, and categories, with progress and recovery features; AI planning, accounts, and encrypted sync are optional extensions. The web client keeps workspace data in IndexedDB, while a Java service provides account, AI, sync, and hosting capabilities. Desktop and mobile shells reuse the web experience. Relationships for unsampled subsystems are included only where the README or source index supports them; some internal API routing details are not shown.

Main entry points: [`apps/web/src/App.tsx`](https://github.com/vpwillwreckyou/momentum/blob/main/apps/web/src/App.tsx) (Web application), [`services/api/src/main/java/dev/momentum/MomentumService.java`](https://github.com/vpwillwreckyou/momentum/blob/main/services/api/src/main/java/dev/momentum/MomentumService.java) (Service API), [`apps/desktop-fx/src/main/java/dev/momentum/desktop/host/ServiceHost.java`](https://github.com/vpwillwreckyou/momentum/blob/main/apps/desktop-fx/src/main/java/dev/momentum/desktop/host/ServiceHost.java) (Windows desktop), [`apps/web/src/pages/PlannerPage.tsx`](https://github.com/vpwillwreckyou/momentum/blob/main/apps/web/src/pages/PlannerPage.tsx) (AI planner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web experience"]
  node_webapp["Web application<br/>[App.tsx]"]
  node_goalpages["Goals and progress"]
  node_planner["AI planner<br/>[PlannerPage.tsx]"]
  node_accountui["Account settings<br/>[AuthPage.tsx]"]
end

subgraph group_workspace["Local workspace"]
  node_context["Workspace state"]
  node_repository["Local repository<br/>[repository.ts]"]
  node_indexeddb[("IndexedDB<br/>[db.ts]")]
end

subgraph group_service["Java service"]
  node_service["Service API"]
  node_ai["AI proxy<br/>[AiProxy.java]"]
  node_database[("SQLite database<br/>[Database.java]")]
  node_sqlrepo["SQL repository"]
end

subgraph group_account["Accounts and sync"]
  node_accounts[("Account store<br/>[AccountStore.java]")]
  node_oauth["OAuth<br/>[OAuthService.java]"]
  node_syncstore[("Encrypted sync<br/>[SyncStore.java]")]
end

subgraph group_platform["Platform shells"]
  node_desktop["Windows desktop<br/>[ServiceHost.java]"]
  node_mobile["Mobile shells"]
end

node_user(("User"))
node_ai_provider{{"AI provider"}}

node_user -->|"uses"| node_webapp
node_webapp -->|"loads state"| node_context
node_webapp -->|"routes to"| node_goalpages
node_webapp -->|"routes to"| node_planner
node_webapp -->|"routes to"| node_accountui
node_context -->|"loads and saves"| node_repository
node_repository -->|"reads and writes"| node_indexeddb
node_planner -.->|"requests planning"| node_service
node_accountui -.->|"uses optional API"| node_service
node_service -->|"delegates accounts"| node_accounts
node_service -->|"delegates OAuth"| node_oauth
node_service -->|"reads and writes sync"| node_syncstore
node_service -->|"delegates AI"| node_ai
node_ai -.->|"proxies requests"| node_ai_provider
node_desktop -->|"opens local store"| node_database
node_desktop -->|"runs repository actions"| node_sqlrepo
node_database -.->|"provides connection"| node_sqlrepo
node_user -->|"launches"| node_desktop
node_user -->|"uses"| node_mobile
node_mobile -->|"bundles same app"| node_webapp

click node_webapp "https://github.com/vpwillwreckyou/momentum/blob/main/apps/web/src/App.tsx"
click node_goalpages "https://github.com/vpwillwreckyou/momentum/tree/main/apps/web/src/pages"
click node_planner "https://github.com/vpwillwreckyou/momentum/blob/main/apps/web/src/pages/PlannerPage.tsx"
click node_accountui "https://github.com/vpwillwreckyou/momentum/blob/main/apps/web/src/pages/AuthPage.tsx"
click node_context "https://github.com/vpwillwreckyou/momentum/blob/main/apps/web/src/state/MomentumContext.tsx"
click node_repository "https://github.com/vpwillwreckyou/momentum/blob/main/apps/web/src/lib/repository.ts"
click node_indexeddb "https://github.com/vpwillwreckyou/momentum/blob/main/apps/web/src/lib/db.ts"
click node_service "https://github.com/vpwillwreckyou/momentum/blob/main/services/api/src/main/java/dev/momentum/MomentumService.java"
click node_ai "https://github.com/vpwillwreckyou/momentum/blob/main/services/api/src/main/java/dev/momentum/ai/AiProxy.java"
click node_accounts "https://github.com/vpwillwreckyou/momentum/blob/main/services/api/src/main/java/dev/momentum/auth/AccountStore.java"
click node_oauth "https://github.com/vpwillwreckyou/momentum/blob/main/services/api/src/main/java/dev/momentum/auth/OAuthService.java"
click node_syncstore "https://github.com/vpwillwreckyou/momentum/blob/main/services/api/src/main/java/dev/momentum/sync/SyncStore.java"
click node_database "https://github.com/vpwillwreckyou/momentum/blob/main/services/api/src/main/java/dev/momentum/data/Database.java"
click node_sqlrepo "https://github.com/vpwillwreckyou/momentum/blob/main/services/api/src/main/java/dev/momentum/data/SqliteRepository.java"
click node_desktop "https://github.com/vpwillwreckyou/momentum/blob/main/apps/desktop-fx/src/main/java/dev/momentum/desktop/host/ServiceHost.java"
click node_mobile "https://github.com/vpwillwreckyou/momentum/tree/main/apps/mobile"

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_webapp,node_goalpages,node_planner,node_accountui,node_user toneBlue
class node_context,node_repository,node_indexeddb toneAmber
class node_service,node_ai,node_database,node_sqlrepo toneMint
class node_accounts,node_oauth,node_syncstore toneRose
class node_desktop,node_mobile,node_ai_provider toneIndigo
```

## Components

### Web experience

- [Web application](https://github.com/vpwillwreckyou/momentum/blob/main/apps/web/src/App.tsx): `apps/web/src/App.tsx`
- [Goals and progress](https://github.com/vpwillwreckyou/momentum/tree/main/apps/web/src/pages): `apps/web/src/pages`
- [AI planner](https://github.com/vpwillwreckyou/momentum/blob/main/apps/web/src/pages/PlannerPage.tsx): `apps/web/src/pages/PlannerPage.tsx`
- [Account settings](https://github.com/vpwillwreckyou/momentum/blob/main/apps/web/src/pages/AuthPage.tsx): `apps/web/src/pages/AuthPage.tsx`

### Local workspace

- [Workspace state](https://github.com/vpwillwreckyou/momentum/blob/main/apps/web/src/state/MomentumContext.tsx): `apps/web/src/state/MomentumContext.tsx`
- [Local repository](https://github.com/vpwillwreckyou/momentum/blob/main/apps/web/src/lib/repository.ts): `apps/web/src/lib/repository.ts`
- [IndexedDB](https://github.com/vpwillwreckyou/momentum/blob/main/apps/web/src/lib/db.ts): `apps/web/src/lib/db.ts`

### Java service

- [Service API](https://github.com/vpwillwreckyou/momentum/blob/main/services/api/src/main/java/dev/momentum/MomentumService.java): `services/api/src/main/java/dev/momentum/MomentumService.java`
- [AI proxy](https://github.com/vpwillwreckyou/momentum/blob/main/services/api/src/main/java/dev/momentum/ai/AiProxy.java): `services/api/src/main/java/dev/momentum/ai/AiProxy.java`
- [SQLite database](https://github.com/vpwillwreckyou/momentum/blob/main/services/api/src/main/java/dev/momentum/data/Database.java): `services/api/src/main/java/dev/momentum/data/Database.java`
- [SQL repository](https://github.com/vpwillwreckyou/momentum/blob/main/services/api/src/main/java/dev/momentum/data/SqliteRepository.java): `services/api/src/main/java/dev/momentum/data/SqliteRepository.java`

### Accounts and sync

- [Account store](https://github.com/vpwillwreckyou/momentum/blob/main/services/api/src/main/java/dev/momentum/auth/AccountStore.java): `services/api/src/main/java/dev/momentum/auth/AccountStore.java`
- [OAuth](https://github.com/vpwillwreckyou/momentum/blob/main/services/api/src/main/java/dev/momentum/auth/OAuthService.java): `services/api/src/main/java/dev/momentum/auth/OAuthService.java`
- [Encrypted sync](https://github.com/vpwillwreckyou/momentum/blob/main/services/api/src/main/java/dev/momentum/sync/SyncStore.java): `services/api/src/main/java/dev/momentum/sync/SyncStore.java`

### Platform shells

- [Windows desktop](https://github.com/vpwillwreckyou/momentum/blob/main/apps/desktop-fx/src/main/java/dev/momentum/desktop/host/ServiceHost.java): `apps/desktop-fx/src/main/java/dev/momentum/desktop/host/ServiceHost.java`
- [Mobile shells](https://github.com/vpwillwreckyou/momentum/tree/main/apps/mobile): `apps/mobile`

### Other components

- **User**
- **AI provider**

## Connections

- User → Web application: uses (evidence: `README.md`)
- Web application → Workspace state: loads state (evidence: `apps/web/src/App.tsx`)
- Web application → Goals and progress: routes to (evidence: `apps/web/src/App.tsx`)
- Web application → AI planner: routes to (evidence: `apps/web/src/App.tsx`)
- Web application → Account settings: routes to (evidence: `apps/web/src/App.tsx`)
- Workspace state → Local repository: loads and saves (evidence: `apps/web/src/state/MomentumContext.tsx`)
- Local repository → IndexedDB: reads and writes (evidence: `apps/web/src/lib/repository.ts`)
- AI planner → Service API: requests planning (evidence: `README.md`)
- Account settings → Service API: uses optional API (evidence: `README.md`)
- Service API → Account store: delegates accounts (evidence: `services/api/src/main/java/dev/momentum/MomentumService.java`)
- Service API → OAuth: delegates OAuth (evidence: `services/api/src/main/java/dev/momentum/MomentumService.java`)
- Service API → Encrypted sync: reads and writes sync (evidence: `services/api/src/main/java/dev/momentum/MomentumService.java`)
- Service API → AI proxy: delegates AI (evidence: `services/api/src/main/java/dev/momentum/MomentumService.java`)
- AI proxy → AI provider: proxies requests (evidence: `README.md`)
- Windows desktop → SQLite database: opens local store (evidence: `apps/desktop-fx/src/main/java/dev/momentum/desktop/host/ServiceHost.java`)
- Windows desktop → SQL repository: runs repository actions (evidence: `apps/desktop-fx/src/main/java/dev/momentum/desktop/host/ServiceHost.java`)
- SQLite database → SQL repository: provides connection (evidence: `services/api/src/main/java/dev/momentum/data/SqliteRepository.java`)
- User → Windows desktop: launches (evidence: `README.md`)
- User → Mobile shells: uses (evidence: `README.md`)
- Mobile shells → Web application: bundles same app (evidence: `README.md`)