# jakezy-kun/scrollq architecture

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

- Interactive diagram: https://gitdiagram.com/jakezy-kun/scrollq
- Repository: https://github.com/jakezy-kun/scrollq

## Overview

ScrollQ is a mobile-first attention-budget learning game. Players choose a curated or live feed, make read/skip/flag decisions under coin and idle-drain rules, then review an SQ score, reveal, and reflection; round history can remain local or sync for signed-in accounts. The graph preserves documented game, feed, account, and history stages. Edges are limited to router and round-state relationships supported by excerpts or README; unsampled feature and provider internals are represented without guessed call chains.

Main entry points: [`src/app/router.tsx`](https://github.com/jakezy-kun/scrollq/blob/main/src/app/router.tsx) (Screen router), [`src/lib/rounds/record.ts`](https://github.com/jakezy-kun/scrollq/blob/main/src/lib/rounds/record.ts) (Round records), [`src/hooks/useRound.ts`](https://github.com/jakezy-kun/scrollq/blob/main/src/hooks/useRound.ts) (Round state), [`src/lib/repository/SupabaseRepository.ts`](https://github.com/jakezy-kun/scrollq/blob/main/src/lib/repository/SupabaseRepository.ts) (Cloud repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App navigation"]
  node_entry["App entry<br/>[main.tsx]"]
  node_router["Screen router<br/>[router.tsx]"]
end

subgraph group_play["Play experience"]
  node_start["Start and setup<br/>[StartPage.tsx]"]
  node_onboarding["Onboarding<br/>[OnboardingPage.tsx]"]
  node_roundpage["Round play<br/>[RoundPage.tsx]"]
  node_summary["Score and reveal<br/>[SummaryPage.tsx]"]
  node_reflection["Reflection<br/>[ReflectPage.tsx]"]
  node_history["Round history<br/>[HistoryPage.tsx]"]
end

subgraph group_game["Game engine"]
  node_roundstate["Round state<br/>[useRound.ts]"]
  node_engine["Rules and scoring<br/>[reducer.ts]"]
  node_engineconfig["Game configuration<br/>[config.ts]"]
  node_idle["Idle drain<br/>[idle.ts]"]
end

subgraph group_content["Feed content"]
  node_feedselect["Feed selection<br/>[FeedSelectPage.tsx]"]
  node_feedproviders["Feed providers"]
  node_livefeed["Live feed service<br/>[pixabay.ts]"]
end

subgraph group_data["Persistence and accounts"]
  node_auth["Authentication<br/>[AuthProvider.tsx]"]
  node_accountpages["Profile and account<br/>[AccountPage.tsx]"]
  node_repository["Repository selection"]
  node_localrepo["Local repository<br/>[LocalRepository.ts]"]
  node_records["Round records<br/>[record.ts]"]
  node_storage[("Browser storage<br/>[storage.ts]")]
  node_cloudrepo["Cloud repository"]
  node_sync["Offline sync queue<br/>[SyncQueue.ts]"]
end

node_player(("Player"))
node_supabase[("Supabase service")]

node_player -->|"opens app"| node_entry
node_entry -->|"mounts"| node_router
node_router -->|"routes to"| node_start
node_router -->|"routes to"| node_onboarding
node_router -->|"routes to"| node_feedselect
node_router -->|"routes to"| node_roundpage
node_router -->|"routes to"| node_summary
node_router -->|"routes to"| node_reflection
node_router -->|"routes to"| node_history
node_feedselect -.->|"selects feed"| node_feedproviders
node_feedproviders -.->|"requests videos"| node_livefeed
node_feedselect -.->|"starts round"| node_roundpage
node_roundpage -.->|"dispatches actions"| node_roundstate
node_roundstate -->|"reduces actions"| node_engine
node_roundstate -->|"snapshots result"| node_records
node_roundstate -->|"persists session"| node_storage
node_engine -.->|"uses rules"| node_engineconfig
node_engine -.->|"checks idle"| node_idle
node_records -->|"derives summary"| node_engine
node_summary -.->|"shows result"| node_records
node_reflection -.->|"adds reflection"| node_records
node_history -.->|"loads rounds"| node_repository
node_auth -.->|"selects account data"| node_repository
node_repository -->|"uses for guests"| node_localrepo
node_localrepo -.->|"reads and writes"| node_storage
node_localrepo -.->|"stores records"| node_records
node_repository -.->|"uses when signed in"| node_cloudrepo
node_cloudrepo -->|"reads and writes"| node_supabase
node_cloudrepo -->|"queues retries"| node_sync
node_cloudrepo -->|"maps records"| node_records
node_player -.->|"signs in"| node_auth

click node_entry "https://github.com/jakezy-kun/scrollq/blob/main/src/main.tsx"
click node_router "https://github.com/jakezy-kun/scrollq/blob/main/src/app/router.tsx"
click node_start "https://github.com/jakezy-kun/scrollq/blob/main/src/features/start/StartPage.tsx"
click node_onboarding "https://github.com/jakezy-kun/scrollq/blob/main/src/features/onboarding/OnboardingPage.tsx"
click node_feedselect "https://github.com/jakezy-kun/scrollq/blob/main/src/features/feed-select/FeedSelectPage.tsx"
click node_feedproviders "https://github.com/jakezy-kun/scrollq/tree/main/src/content"
click node_livefeed "https://github.com/jakezy-kun/scrollq/blob/main/src/server/pixabay.ts"
click node_roundpage "https://github.com/jakezy-kun/scrollq/blob/main/src/features/round/RoundPage.tsx"
click node_roundstate "https://github.com/jakezy-kun/scrollq/blob/main/src/hooks/useRound.ts"
click node_engine "https://github.com/jakezy-kun/scrollq/blob/main/src/engine/reducer.ts"
click node_engineconfig "https://github.com/jakezy-kun/scrollq/blob/main/src/engine/config.ts"
click node_idle "https://github.com/jakezy-kun/scrollq/blob/main/src/engine/idle.ts"
click node_summary "https://github.com/jakezy-kun/scrollq/blob/main/src/features/summary/SummaryPage.tsx"
click node_reflection "https://github.com/jakezy-kun/scrollq/blob/main/src/features/reflect/ReflectPage.tsx"
click node_history "https://github.com/jakezy-kun/scrollq/blob/main/src/features/history/HistoryPage.tsx"
click node_auth "https://github.com/jakezy-kun/scrollq/blob/main/src/lib/auth/AuthProvider.tsx"
click node_accountpages "https://github.com/jakezy-kun/scrollq/blob/main/src/features/account/AccountPage.tsx"
click node_repository "https://github.com/jakezy-kun/scrollq/blob/main/src/lib/repository/RepositoryProvider.tsx"
click node_localrepo "https://github.com/jakezy-kun/scrollq/blob/main/src/lib/repository/LocalRepository.ts"
click node_records "https://github.com/jakezy-kun/scrollq/blob/main/src/lib/rounds/record.ts"
click node_storage "https://github.com/jakezy-kun/scrollq/blob/main/src/lib/storage.ts"
click node_cloudrepo "https://github.com/jakezy-kun/scrollq/blob/main/src/lib/repository/SupabaseRepository.ts"
click node_sync "https://github.com/jakezy-kun/scrollq/blob/main/src/lib/sync/SyncQueue.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_entry,node_router toneBlue
class node_start,node_onboarding,node_roundpage,node_summary,node_reflection,node_history,node_supabase toneAmber
class node_roundstate,node_engine,node_engineconfig,node_idle toneMint
class node_feedselect,node_feedproviders,node_livefeed toneRose
class node_auth,node_accountpages,node_repository,node_localrepo,node_records,node_storage,node_cloudrepo,node_sync,node_player toneIndigo
```

## Components

### App navigation

- [App entry](https://github.com/jakezy-kun/scrollq/blob/main/src/main.tsx): `src/main.tsx`
- [Screen router](https://github.com/jakezy-kun/scrollq/blob/main/src/app/router.tsx): `src/app/router.tsx`

### Play experience

- [Start and setup](https://github.com/jakezy-kun/scrollq/blob/main/src/features/start/StartPage.tsx): `src/features/start/StartPage.tsx`
- [Onboarding](https://github.com/jakezy-kun/scrollq/blob/main/src/features/onboarding/OnboardingPage.tsx): `src/features/onboarding/OnboardingPage.tsx`
- [Round play](https://github.com/jakezy-kun/scrollq/blob/main/src/features/round/RoundPage.tsx): `src/features/round/RoundPage.tsx`
- [Score and reveal](https://github.com/jakezy-kun/scrollq/blob/main/src/features/summary/SummaryPage.tsx): `src/features/summary/SummaryPage.tsx`
- [Reflection](https://github.com/jakezy-kun/scrollq/blob/main/src/features/reflect/ReflectPage.tsx): `src/features/reflect/ReflectPage.tsx`
- [Round history](https://github.com/jakezy-kun/scrollq/blob/main/src/features/history/HistoryPage.tsx): `src/features/history/HistoryPage.tsx`

### Game engine

- [Round state](https://github.com/jakezy-kun/scrollq/blob/main/src/hooks/useRound.ts): `src/hooks/useRound.ts`
- [Rules and scoring](https://github.com/jakezy-kun/scrollq/blob/main/src/engine/reducer.ts): `src/engine/reducer.ts`
- [Game configuration](https://github.com/jakezy-kun/scrollq/blob/main/src/engine/config.ts): `src/engine/config.ts`
- [Idle drain](https://github.com/jakezy-kun/scrollq/blob/main/src/engine/idle.ts): `src/engine/idle.ts`

### Feed content

- [Feed selection](https://github.com/jakezy-kun/scrollq/blob/main/src/features/feed-select/FeedSelectPage.tsx): `src/features/feed-select/FeedSelectPage.tsx`
- [Feed providers](https://github.com/jakezy-kun/scrollq/tree/main/src/content): `src/content`
- [Live feed service](https://github.com/jakezy-kun/scrollq/blob/main/src/server/pixabay.ts): `src/server/pixabay.ts`

### Persistence and accounts

- [Authentication](https://github.com/jakezy-kun/scrollq/blob/main/src/lib/auth/AuthProvider.tsx): `src/lib/auth/AuthProvider.tsx`
- [Profile and account](https://github.com/jakezy-kun/scrollq/blob/main/src/features/account/AccountPage.tsx): `src/features/account/AccountPage.tsx`
- [Repository selection](https://github.com/jakezy-kun/scrollq/blob/main/src/lib/repository/RepositoryProvider.tsx): `src/lib/repository/RepositoryProvider.tsx`
- [Local repository](https://github.com/jakezy-kun/scrollq/blob/main/src/lib/repository/LocalRepository.ts): `src/lib/repository/LocalRepository.ts`
- [Round records](https://github.com/jakezy-kun/scrollq/blob/main/src/lib/rounds/record.ts): `src/lib/rounds/record.ts`
- [Browser storage](https://github.com/jakezy-kun/scrollq/blob/main/src/lib/storage.ts): `src/lib/storage.ts`
- [Cloud repository](https://github.com/jakezy-kun/scrollq/blob/main/src/lib/repository/SupabaseRepository.ts): `src/lib/repository/SupabaseRepository.ts`
- [Offline sync queue](https://github.com/jakezy-kun/scrollq/blob/main/src/lib/sync/SyncQueue.ts): `src/lib/sync/SyncQueue.ts`

### Other components

- **Player**
- **Supabase service**

## Connections

- Player → App entry: opens app (evidence: `src/main.tsx`)
- App entry → Screen router: mounts (evidence: `src/main.tsx`)
- Screen router → Start and setup: routes to (evidence: `src/app/router.tsx`)
- Screen router → Onboarding: routes to (evidence: `src/app/router.tsx`)
- Screen router → Feed selection: routes to (evidence: `src/app/router.tsx`)
- Screen router → Round play: routes to (evidence: `src/app/router.tsx`)
- Screen router → Score and reveal: routes to (evidence: `src/app/router.tsx`)
- Screen router → Reflection: routes to (evidence: `src/app/router.tsx`)
- Screen router → Round history: routes to (evidence: `src/app/router.tsx`)
- Feed selection → Feed providers: selects feed
- Feed providers → Live feed service: requests videos (evidence: `src/server/pixabay.ts`)
- Feed selection → Round play: starts round
- Round play → Round state: dispatches actions
- Round state → Rules and scoring: reduces actions (evidence: `src/hooks/useRound.ts`)
- Round state → Round records: snapshots result (evidence: `src/hooks/useRound.ts`)
- Round state → Browser storage: persists session (evidence: `src/hooks/useRound.ts`)
- Rules and scoring → Game configuration: uses rules
- Rules and scoring → Idle drain: checks idle
- Round records → Rules and scoring: derives summary (evidence: `src/lib/rounds/record.ts`)
- Score and reveal → Round records: shows result
- Reflection → Round records: adds reflection
- Round history → Repository selection: loads rounds
- Authentication → Repository selection: selects account data
- Repository selection → Local repository: uses for guests
- Local repository → Browser storage: reads and writes (evidence: `src/lib/repository/LocalRepository.ts`)
- Local repository → Round records: stores records (evidence: `src/lib/repository/LocalRepository.ts`)
- Repository selection → Cloud repository: uses when signed in
- Cloud repository → Supabase service: reads and writes (evidence: `src/lib/repository/SupabaseRepository.ts`)
- Cloud repository → Offline sync queue: queues retries (evidence: `src/lib/repository/SupabaseRepository.ts`)
- Cloud repository → Round records: maps records (evidence: `src/lib/repository/SupabaseRepository.ts`)
- Player → Authentication: signs in