# themoldymustard/sentinelquiz architecture

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

- Interactive diagram: https://gitdiagram.com/themoldymustard/sentinelquiz
- Repository: https://github.com/themoldymustard/sentinelquiz

## Overview

SentinelQuiz turns imported quiz JSON into configurable practice sessions across identification, multiple-choice, and multiple-select modes, then scores answers and presents a breakdown. The shown home page also saves and manages quizzes in browser IndexedDB. The README documents Supabase tables, row-level security, and authentication, but the sampled app code does not show those services wired into the workflow; they are represented as a documented, separate capability. Edges reflect sampled calls and SOURCE INDEX references; no Supabase runtime connection is inferred.

Main entry points: [`components/QuizEngine.tsx`](https://github.com/themoldymustard/sentinelquiz/blob/main/components/QuizEngine.tsx) (Quiz orchestrator), [`app/page.tsx`](https://github.com/themoldymustard/sentinelquiz/blob/main/app/page.tsx) (Import and setup), [`components/ImportModule.tsx`](https://github.com/themoldymustard/sentinelquiz/blob/main/components/ImportModule.tsx) (JSON import UI), [`lib/fsm.ts`](https://github.com/themoldymustard/sentinelquiz/blob/main/lib/fsm.ts) (Quiz state machine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_intake["Import and library"]
  node_home["Import and setup<br/>[page.tsx]"]
  node_import_ui["JSON import UI<br/>[ImportModule.tsx]"]
  node_validation["Schema validation<br/>[quiz.ts]"]
  node_sanitization["Content sanitization<br/>[sanitize.ts]"]
  node_saved_library["Saved quiz library<br/>[storage.ts]"]
  node_indexeddb[("Browser quiz store<br/>[storage.ts]")]
end

subgraph group_session["Session experience"]
  node_quiz_route["Session runner page<br/>[page.tsx]"]
  node_pwa_manifest["PWA manifest<br/>[manifest.json]"]
end

subgraph group_engine["Quiz engine"]
  node_engine_ui["Quiz orchestrator<br/>[QuizEngine.tsx]"]
  node_identification["Identification mode"]
  node_multiple_choice["Multiple choice mode"]
  node_multiple_select["Multiple select mode"]
  node_score_display["Results display<br/>[ScoreDisplay.tsx]"]
  node_multiple_select_types["Multiple-select UI"]
end

subgraph group_shared["Shared logic"]
  node_fsm["Quiz state machine<br/>[fsm.ts]"]
  node_answer_logic["Answer matching<br/>[answers.ts]"]
  node_quiz_types["Quiz types and scoring<br/>[quiz.ts]"]
end

subgraph group_backend["Documented backend"]
  node_supabase_clients["Supabase clients<br/>[client.ts]"]
  node_database_schema[("Database schema and RLS<br/>[001_initial.sql]")]
end

node_learner(("Learner"))

node_learner -->|"imports quiz"| node_home
node_home -->|"renders"| node_import_ui
node_import_ui -->|"validates JSON"| node_validation
node_import_ui -->|"sanitizes items"| node_sanitization
node_import_ui -->|"returns items"| node_home
node_home -->|"loads and manages"| node_saved_library
node_saved_library -->|"reads and writes"| node_indexeddb
node_home -->|"uses quiz types"| node_quiz_types
node_quiz_route -->|"renders session"| node_engine_ui
node_quiz_route -->|"uses session types"| node_quiz_types
node_engine_ui -->|"dispatches and selects"| node_fsm
node_engine_ui -->|"renders mode"| node_identification
node_engine_ui -->|"renders mode"| node_multiple_choice
node_engine_ui -->|"renders mode"| node_multiple_select
node_engine_ui -->|"renders results"| node_score_display
node_engine_ui -->|"normalizes answers"| node_answer_logic
node_fsm -->|"checks answers"| node_answer_logic
node_fsm -->|"uses state and scoring types"| node_quiz_types
node_multiple_choice -->|"uses answer matching"| node_answer_logic
node_multiple_select -->|"uses answer matching"| node_answer_logic
node_score_display -->|"uses final stats"| node_fsm
node_score_display -->|"uses answer records"| node_quiz_types

click node_home "https://github.com/themoldymustard/sentinelquiz/blob/main/app/page.tsx"
click node_import_ui "https://github.com/themoldymustard/sentinelquiz/blob/main/components/ImportModule.tsx"
click node_validation "https://github.com/themoldymustard/sentinelquiz/blob/main/lib/schemas/quiz.ts"
click node_sanitization "https://github.com/themoldymustard/sentinelquiz/blob/main/lib/sanitize.ts"
click node_saved_library "https://github.com/themoldymustard/sentinelquiz/blob/main/lib/storage.ts"
click node_indexeddb "https://github.com/themoldymustard/sentinelquiz/blob/main/lib/storage.ts"
click node_quiz_route "https://github.com/themoldymustard/sentinelquiz/blob/main/app/quiz/page.tsx"
click node_engine_ui "https://github.com/themoldymustard/sentinelquiz/blob/main/components/QuizEngine.tsx"
click node_identification "https://github.com/themoldymustard/sentinelquiz/blob/main/components/IdentificationMode.tsx"
click node_multiple_choice "https://github.com/themoldymustard/sentinelquiz/blob/main/components/MultipleChoiceMode.tsx"
click node_multiple_select "https://github.com/themoldymustard/sentinelquiz/blob/main/components/MultipleSelectMode.tsx"
click node_score_display "https://github.com/themoldymustard/sentinelquiz/blob/main/components/ScoreDisplay.tsx"
click node_fsm "https://github.com/themoldymustard/sentinelquiz/blob/main/lib/fsm.ts"
click node_answer_logic "https://github.com/themoldymustard/sentinelquiz/blob/main/lib/answers.ts"
click node_quiz_types "https://github.com/themoldymustard/sentinelquiz/blob/main/types/quiz.ts"
click node_multiple_select_types "https://github.com/themoldymustard/sentinelquiz/blob/main/components/MultipleSelectMode.tsx"
click node_supabase_clients "https://github.com/themoldymustard/sentinelquiz/blob/main/lib/supabase/client.ts"
click node_database_schema "https://github.com/themoldymustard/sentinelquiz/blob/main/supabase/migrations/001_initial.sql"
click node_pwa_manifest "https://github.com/themoldymustard/sentinelquiz/blob/main/public/manifest.json"

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_home,node_import_ui,node_validation,node_sanitization,node_saved_library,node_indexeddb toneBlue
class node_quiz_route,node_pwa_manifest toneAmber
class node_engine_ui,node_identification,node_multiple_choice,node_multiple_select,node_score_display,node_multiple_select_types toneMint
class node_fsm,node_answer_logic,node_quiz_types toneRose
class node_supabase_clients,node_database_schema,node_learner toneIndigo
```

## Components

### Import and library

- [Import and setup](https://github.com/themoldymustard/sentinelquiz/blob/main/app/page.tsx): `app/page.tsx`
- [JSON import UI](https://github.com/themoldymustard/sentinelquiz/blob/main/components/ImportModule.tsx): `components/ImportModule.tsx`
- [Schema validation](https://github.com/themoldymustard/sentinelquiz/blob/main/lib/schemas/quiz.ts): `lib/schemas/quiz.ts`
- [Content sanitization](https://github.com/themoldymustard/sentinelquiz/blob/main/lib/sanitize.ts): `lib/sanitize.ts`
- [Saved quiz library](https://github.com/themoldymustard/sentinelquiz/blob/main/lib/storage.ts): `lib/storage.ts`
- [Browser quiz store](https://github.com/themoldymustard/sentinelquiz/blob/main/lib/storage.ts): `lib/storage.ts`

### Session experience

- [Session runner page](https://github.com/themoldymustard/sentinelquiz/blob/main/app/quiz/page.tsx): `app/quiz/page.tsx`
- [PWA manifest](https://github.com/themoldymustard/sentinelquiz/blob/main/public/manifest.json): `public/manifest.json`

### Quiz engine

- [Quiz orchestrator](https://github.com/themoldymustard/sentinelquiz/blob/main/components/QuizEngine.tsx): `components/QuizEngine.tsx`
- [Identification mode](https://github.com/themoldymustard/sentinelquiz/blob/main/components/IdentificationMode.tsx): `components/IdentificationMode.tsx`
- [Multiple choice mode](https://github.com/themoldymustard/sentinelquiz/blob/main/components/MultipleChoiceMode.tsx): `components/MultipleChoiceMode.tsx`
- [Multiple select mode](https://github.com/themoldymustard/sentinelquiz/blob/main/components/MultipleSelectMode.tsx): `components/MultipleSelectMode.tsx`
- [Results display](https://github.com/themoldymustard/sentinelquiz/blob/main/components/ScoreDisplay.tsx): `components/ScoreDisplay.tsx`
- [Multiple-select UI](https://github.com/themoldymustard/sentinelquiz/blob/main/components/MultipleSelectMode.tsx): `components/MultipleSelectMode.tsx`

### Shared logic

- [Quiz state machine](https://github.com/themoldymustard/sentinelquiz/blob/main/lib/fsm.ts): `lib/fsm.ts`
- [Answer matching](https://github.com/themoldymustard/sentinelquiz/blob/main/lib/answers.ts): `lib/answers.ts`
- [Quiz types and scoring](https://github.com/themoldymustard/sentinelquiz/blob/main/types/quiz.ts): `types/quiz.ts`

### Documented backend

- [Supabase clients](https://github.com/themoldymustard/sentinelquiz/blob/main/lib/supabase/client.ts): `lib/supabase/client.ts`
- [Database schema and RLS](https://github.com/themoldymustard/sentinelquiz/blob/main/supabase/migrations/001_initial.sql): `supabase/migrations/001_initial.sql`

### Other components

- **Learner**

## Connections

- Learner → Import and setup: imports quiz
- Import and setup → JSON import UI: renders (evidence: `app/page.tsx`)
- JSON import UI → Schema validation: validates JSON (evidence: `components/ImportModule.tsx`)
- JSON import UI → Content sanitization: sanitizes items (evidence: `components/ImportModule.tsx`)
- JSON import UI → Import and setup: returns items (evidence: `components/ImportModule.tsx`)
- Import and setup → Saved quiz library: loads and manages (evidence: `app/page.tsx`)
- Saved quiz library → Browser quiz store: reads and writes (evidence: `lib/storage.ts`)
- Import and setup → Quiz types and scoring: uses quiz types (evidence: `app/page.tsx`)
- Session runner page → Quiz orchestrator: renders session (evidence: `app/quiz/page.tsx`)
- Session runner page → Quiz types and scoring: uses session types (evidence: `app/quiz/page.tsx`)
- Quiz orchestrator → Quiz state machine: dispatches and selects (evidence: `components/QuizEngine.tsx`)
- Quiz orchestrator → Identification mode: renders mode (evidence: `components/QuizEngine.tsx`)
- Quiz orchestrator → Multiple choice mode: renders mode (evidence: `components/QuizEngine.tsx`)
- Quiz orchestrator → Multiple select mode: renders mode (evidence: `components/QuizEngine.tsx`)
- Quiz orchestrator → Results display: renders results (evidence: `components/QuizEngine.tsx`)
- Quiz orchestrator → Answer matching: normalizes answers (evidence: `components/QuizEngine.tsx`)
- Quiz state machine → Answer matching: checks answers (evidence: `lib/fsm.ts`)
- Quiz state machine → Quiz types and scoring: uses state and scoring types (evidence: `lib/fsm.ts`)
- Multiple choice mode → Answer matching: uses answer matching (evidence: `components/MultipleChoiceMode.tsx`)
- Multiple select mode → Answer matching: uses answer matching (evidence: `components/MultipleSelectMode.tsx`)
- Results display → Quiz state machine: uses final stats (evidence: `components/ScoreDisplay.tsx`)
- Results display → Quiz types and scoring: uses answer records (evidence: `components/ScoreDisplay.tsx`)
