# au-cu/sense-vocab architecture

> Architecture diagram of the GitHub repository au-cu/sense-vocab, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/au-cu/sense-vocab
- Repository: https://github.com/au-cu/sense-vocab

## Overview

Sense Vocab is a browser-based English vocabulary learning app centered on learning individual word senses. Its main workflow presents a daily plan, guides the learner through new words, reinforcement, and review, then records progress locally and synchronizes account snapshots across devices. Separate capabilities cover account management and backup, feedback and admin operations, and a public content-attribution directory. Edges below rely on README statements because the sampled source excerpts do not show most runtime wiring; unsampled implementation details are not inferred.

Main entry points: [`cloud-client.js`](https://github.com/au-cu/sense-vocab/blob/main/cloud-client.js) (Cloud client), [`app.js`](https://github.com/au-cu/sense-vocab/blob/main/app.js) (Study and review), [`sync-state.js`](https://github.com/au-cu/sense-vocab/blob/main/sync-state.js) (Sync and merge), [`account.js`](https://github.com/au-cu/sense-vocab/blob/main/account.js) (Account UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_learning["Learning experience"]
  node_learning_app["Learning app<br/>[app.js]"]
  node_study_flow["Study and review<br/>[app.js]"]
  node_vocabulary["Vocabulary pool"]
  node_local_progress[("Local progress<br/>[app.js]")]
end

subgraph group_identity["Accounts and sync"]
  node_account_ui["Account UI<br/>[account.js]"]
  node_sync_logic["Sync and merge<br/>[sync-state.js]"]
  node_cloud_client["Cloud client<br/>[cloud-client.js]"]
end

subgraph group_operations["Feedback and admin"]
  node_feedback["Feedback submission<br/>[account.js]"]
  node_admin_ui["Admin console<br/>[admin.js]"]
  node_retention_job["Feedback retention<br/>[index.ts]"]
end

subgraph group_transparency["Content transparency"]
  node_legal_ui["Sources directory<br/>[legal-sources.js]"]
  node_legal_config["Legal configuration<br/>[legal-config.js]"]
end

node_learner(("Learner"))
node_supabase[("Supabase")]

node_learner -->|"uses"| node_learning_app
node_learning_app -->|"presents"| node_study_flow
node_study_flow -->|"loads senses"| node_vocabulary
node_study_flow -->|"records progress"| node_local_progress
node_learner -->|"manages account"| node_account_ui
node_account_ui -->|"synchronizes"| node_sync_logic
node_sync_logic -->|"calls"| node_cloud_client
node_cloud_client -->|"reads and writes"| node_supabase
node_sync_logic -->|"caches snapshot"| node_local_progress
node_learner -->|"submits"| node_feedback
node_feedback -->|"uploads feedback"| node_cloud_client
node_admin_ui -->|"requests admin data"| node_cloud_client
node_cloud_client -->|"calls RPCs"| node_supabase
node_retention_job -.->|"processes retention"| node_supabase
node_learner -->|"browses sources"| node_legal_ui
node_legal_ui -.->|"uses settings"| node_legal_config

click node_learning_app "https://github.com/au-cu/sense-vocab/blob/main/app.js"
click node_study_flow "https://github.com/au-cu/sense-vocab/blob/main/app.js"
click node_local_progress "https://github.com/au-cu/sense-vocab/blob/main/app.js"
click node_account_ui "https://github.com/au-cu/sense-vocab/blob/main/account.js"
click node_sync_logic "https://github.com/au-cu/sense-vocab/blob/main/sync-state.js"
click node_cloud_client "https://github.com/au-cu/sense-vocab/blob/main/cloud-client.js"
click node_feedback "https://github.com/au-cu/sense-vocab/blob/main/account.js"
click node_admin_ui "https://github.com/au-cu/sense-vocab/blob/main/admin.js"
click node_retention_job "https://github.com/au-cu/sense-vocab/blob/main/supabase/functions/process-feedback-retention/index.ts"
click node_legal_ui "https://github.com/au-cu/sense-vocab/blob/main/legal-sources.js"
click node_legal_config "https://github.com/au-cu/sense-vocab/blob/main/legal-config.js"

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_learning_app,node_study_flow,node_vocabulary,node_local_progress toneBlue
class node_account_ui,node_sync_logic,node_cloud_client,node_supabase toneAmber
class node_feedback,node_admin_ui,node_retention_job toneMint
class node_legal_ui,node_legal_config toneRose
class node_learner toneIndigo
```

## Components

### Learning experience

- [Learning app](https://github.com/au-cu/sense-vocab/blob/main/app.js): `app.js`
- [Study and review](https://github.com/au-cu/sense-vocab/blob/main/app.js): `app.js`
- **Vocabulary pool**
- [Local progress](https://github.com/au-cu/sense-vocab/blob/main/app.js): `app.js`

### Accounts and sync

- [Account UI](https://github.com/au-cu/sense-vocab/blob/main/account.js): `account.js`
- [Sync and merge](https://github.com/au-cu/sense-vocab/blob/main/sync-state.js): `sync-state.js`
- [Cloud client](https://github.com/au-cu/sense-vocab/blob/main/cloud-client.js): `cloud-client.js`

### Feedback and admin

- [Feedback submission](https://github.com/au-cu/sense-vocab/blob/main/account.js): `account.js`
- [Admin console](https://github.com/au-cu/sense-vocab/blob/main/admin.js): `admin.js`
- [Feedback retention](https://github.com/au-cu/sense-vocab/blob/main/supabase/functions/process-feedback-retention/index.ts): `supabase/functions/process-feedback-retention/index.ts`

### Content transparency

- [Sources directory](https://github.com/au-cu/sense-vocab/blob/main/legal-sources.js): `legal-sources.js`
- [Legal configuration](https://github.com/au-cu/sense-vocab/blob/main/legal-config.js): `legal-config.js`

### Other components

- **Learner**
- **Supabase**

## Connections

- Learner → Learning app: uses (evidence: `README.md`)
- Learning app → Study and review: presents (evidence: `README.md`)
- Study and review → Vocabulary pool: loads senses (evidence: `README.md`)
- Study and review → Local progress: records progress (evidence: `README.md`)
- Learner → Account UI: manages account (evidence: `README.md`)
- Account UI → Sync and merge: synchronizes (evidence: `README.md`)
- Sync and merge → Cloud client: calls (evidence: `README.md`)
- Cloud client → Supabase: reads and writes (evidence: `README.md`)
- Sync and merge → Local progress: caches snapshot (evidence: `README.md`)
- Learner → Feedback submission: submits (evidence: `README.md`)
- Feedback submission → Cloud client: uploads feedback (evidence: `README.md`)
- Admin console → Cloud client: requests admin data (evidence: `README.md`)
- Cloud client → Supabase: calls RPCs (evidence: `README.md`)
- Feedback retention → Supabase: processes retention
- Learner → Sources directory: browses sources (evidence: `README.md`)
- Sources directory → Legal configuration: uses settings
