# gholsona171/policy-prep architecture

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

- Interactive diagram: https://gitdiagram.com/gholsona171/policy-prep
- Repository: https://github.com/gholsona171/policy-prep
- Video tour (about a minute): https://gitdiagram.com/gholsona171/policy-prep/video

## Overview

Policy Prep is an offline-capable promotion-exam study app. The learner loads policy material, studies and answers questions one policy at a time, and advances only after meeting the coverage, score, and repeat-miss gate. The app also provides reading, progress views, and optional online features. Source excerpts show policy content mirrored from Supabase as well as stored locally, while the README describes owner-loaded local packs and says there is no backend; the excerpts do not establish how local pack import works, so that link is omitted. Major UI behavior is consolidated under app.js because its source is partial.

Main entry points: [`app.js`](https://github.com/gholsona171/policy-prep/blob/main/app.js) (Study app), [`supa.js`](https://github.com/gholsona171/policy-prep/blob/main/supa.js) (Supabase client), [`engine.js`](https://github.com/gholsona171/policy-prep/blob/main/engine.js) (Session and gate engine), [`content-store.js`](https://github.com/gholsona171/policy-prep/blob/main/content-store.js) (Content cache)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_study["Study workflow"]
  node_app["Study app<br/>[app.js]"]
  node_engine["Session and gate engine<br/>[engine.js]"]
  node_policytext["Policy reading<br/>[app.js]"]
  node_pdfaudio["PDF and narration<br/>[app.js]"]
  node_progressview["Progress and review<br/>[app.js]"]
end

subgraph group_device["On-device data"]
  node_localstate[("App state<br/>[app.js]")]
  node_contentstore[("Content cache<br/>[content-store.js]")]
end

subgraph group_online["Online services"]
  node_sync["Content and progress sync<br/>[sync.js]"]
  node_client["Supabase client<br/>[supa.js]"]
  node_suggestions["Suggestions and account tools<br/>[app.js]"]
end

subgraph group_shell["Offline app shell"]
  node_offline["Offline app shell<br/>[sw.js]"]
end

node_learner(("Learner"))
node_browserstorage[("Browser storage")]
node_supabase[("Supabase service")]
node_browser(("Web browser"))

node_learner -->|"uses"| node_app
node_app -->|"builds sessions; checks gates"| node_engine
node_engine -->|"returns session and gate results"| node_app
node_app -->|"shows reading"| node_policytext
node_app -->|"opens documents; fetches audio"| node_pdfaudio
node_app -->|"renders progress and review"| node_progressview
node_app -->|"updates"| node_localstate
node_app -->|"reads and writes content"| node_contentstore
node_contentstore -->|"stores content in IndexedDB"| node_browserstorage
node_localstate -->|"persists app state"| node_browserstorage
node_app -->|"starts sync"| node_sync
node_sync -->|"reads and writes through"| node_client
node_app -->|"calls account and document APIs"| node_client
node_client -->|"authenticates; accesses data"| node_supabase
node_app -->|"submits and reads suggestions"| node_suggestions
node_suggestions -->|"uses database APIs"| node_client
node_browser -->|"runs"| node_offline
node_offline -->|"caches app shell"| node_browser

click node_app "https://github.com/gholsona171/policy-prep/blob/main/app.js"
click node_engine "https://github.com/gholsona171/policy-prep/blob/main/engine.js"
click node_policytext "https://github.com/gholsona171/policy-prep/blob/main/app.js"
click node_pdfaudio "https://github.com/gholsona171/policy-prep/blob/main/app.js"
click node_progressview "https://github.com/gholsona171/policy-prep/blob/main/app.js"
click node_localstate "https://github.com/gholsona171/policy-prep/blob/main/app.js"
click node_contentstore "https://github.com/gholsona171/policy-prep/blob/main/content-store.js"
click node_sync "https://github.com/gholsona171/policy-prep/blob/main/sync.js"
click node_client "https://github.com/gholsona171/policy-prep/blob/main/supa.js"
click node_suggestions "https://github.com/gholsona171/policy-prep/blob/main/app.js"
click node_offline "https://github.com/gholsona171/policy-prep/blob/main/sw.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_app,node_engine,node_policytext,node_pdfaudio,node_progressview,node_browser toneBlue
class node_localstate,node_contentstore,node_browserstorage,node_supabase toneAmber
class node_sync,node_client,node_suggestions toneMint
class node_offline toneRose
class node_learner toneIndigo
```

## Components

### Study workflow

- [Study app](https://github.com/gholsona171/policy-prep/blob/main/app.js): `app.js`
- [Session and gate engine](https://github.com/gholsona171/policy-prep/blob/main/engine.js): `engine.js`
- [Policy reading](https://github.com/gholsona171/policy-prep/blob/main/app.js): `app.js`
- [PDF and narration](https://github.com/gholsona171/policy-prep/blob/main/app.js): `app.js`
- [Progress and review](https://github.com/gholsona171/policy-prep/blob/main/app.js): `app.js`

### On-device data

- [App state](https://github.com/gholsona171/policy-prep/blob/main/app.js): `app.js`
- [Content cache](https://github.com/gholsona171/policy-prep/blob/main/content-store.js): `content-store.js`

### Online services

- [Content and progress sync](https://github.com/gholsona171/policy-prep/blob/main/sync.js): `sync.js`
- [Supabase client](https://github.com/gholsona171/policy-prep/blob/main/supa.js): `supa.js`
- [Suggestions and account tools](https://github.com/gholsona171/policy-prep/blob/main/app.js): `app.js`

### Offline app shell

- [Offline app shell](https://github.com/gholsona171/policy-prep/blob/main/sw.js): `sw.js`

### Other components

- **Learner**
- **Browser storage**
- **Supabase service**
- **Web browser**

## Connections

- Learner → Study app: uses
- Study app → Session and gate engine: builds sessions; checks gates
- Session and gate engine → Study app: returns session and gate results
- Study app → Policy reading: shows reading
- Study app → PDF and narration: opens documents; fetches audio
- Study app → Progress and review: renders progress and review
- Study app → App state: updates
- Study app → Content cache: reads and writes content
- Content cache → Browser storage: stores content in IndexedDB
- App state → Browser storage: persists app state
- Study app → Content and progress sync: starts sync
- Content and progress sync → Supabase client: reads and writes through
- Study app → Supabase client: calls account and document APIs
- Supabase client → Supabase service: authenticates; accesses data
- Study app → Suggestions and account tools: submits and reads suggestions
- Suggestions and account tools → Supabase client: uses database APIs
- Web browser → Offline app shell: runs
- Offline app shell → Web browser: caches app shell