# cmmhero/zentype architecture

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

- Interactive diagram: https://gitdiagram.com/cmmhero/zentype
- Repository: https://github.com/cmmhero/zentype

## Overview

zentype is a customizable typing-test app with guest-first local play and optional cloud accounts. The main flow configures a prompt, runs the typing engine, computes a result, saves it locally or to the cloud, then processes XP and achievements; profile and leaderboard views expose accumulated stats. The map also captures documented appearance, account, and discovery capabilities. Source excerpts are partial, so unsampled feature wiring is shown only where the README documents it.

Main entry points: [`src/app/page.tsx`](https://github.com/cmmhero/zentype/blob/main/src/app/page.tsx) (Typing page), [`src/lib/supabase/server.ts`](https://github.com/cmmhero/zentype/blob/main/src/lib/supabase/server.ts) (Supabase client), [`src/server/gamification.ts`](https://github.com/cmmhero/zentype/blob/main/src/server/gamification.ts) (Progress processing), [`src/server/leaderboard.ts`](https://github.com/cmmhero/zentype/blob/main/src/server/leaderboard.ts) (Ranking service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_play["Typing experience"]
  node_test_page["Typing page<br/>[page.tsx]"]
  node_typing_ui["Typing display<br/>[typing-display.tsx]"]
  node_typing_engine["Typing engine"]
  node_prompt_server["Prompt service<br/>[prompts.ts]"]
  node_prompt_utils["Prompt utilities<br/>[prompt-utils.ts]"]
end

subgraph group_progress["Results and progress"]
  node_results_server["Result service<br/>[results.ts]"]
  node_results_store["Guest results<br/>[results-store.ts]"]
  node_gamification["Progress processing<br/>[gamification.ts]"]
  node_achievements["Achievement rules<br/>[achievements.ts]"]
  node_profile_page["Profile dashboard<br/>[page.tsx]"]
  node_public_profile["Public profile<br/>[page.tsx]"]
end

subgraph group_account["Account and settings"]
  node_settings_page["Settings<br/>[page.tsx]"]
  node_settings_store["Settings state<br/>[settings-store.ts]"]
  node_settings_sync["Settings sync"]
  node_auth_server["Auth actions<br/>[auth.ts]"]
  node_auth_callback["OAuth callback<br/>[route.ts]"]
end

subgraph group_discovery["Community and discovery"]
  node_leaderboard_page["Leaderboards<br/>[page.tsx]"]
  node_leaderboard_server["Ranking service<br/>[leaderboard.ts]"]
  node_command_palette["Command palette"]
end

subgraph group_infra["Persistence services"]
  node_supabase_client["Supabase client<br/>[server.ts]"]
  node_supabase[("Supabase")]
  node_redis[("Redis rankings<br/>[redis.ts]")]
  node_postgres[("Postgres")]
end

node_visitor(("Player"))

node_visitor -->|"starts test"| node_test_page
node_test_page -->|"renders test"| node_typing_ui
node_typing_ui -->|"runs engine"| node_typing_engine
node_test_page -->|"requests prompt"| node_prompt_server
node_test_page -->|"fallback prompt"| node_prompt_utils
node_test_page -->|"saves result"| node_results_server
node_test_page -->|"keeps guest results"| node_results_store
node_test_page -->|"processes saved result"| node_gamification
node_gamification -->|"checks progress"| node_achievements
node_results_server -->|"uses cloud client"| node_supabase_client
node_supabase_client -->|"reads and writes"| node_supabase
node_gamification -->|"persists progress"| node_supabase_client
node_settings_page -->|"updates settings"| node_settings_store
node_settings_sync -->|"syncs settings"| node_settings_store
node_settings_sync -->|"syncs cloud settings"| node_supabase_client
node_auth_server -->|"uses session client"| node_supabase_client
node_auth_callback -->|"exchanges OAuth code"| node_supabase_client
node_profile_page -.->|"loads account data"| node_supabase_client
node_public_profile -.->|"loads public data"| node_supabase_client
node_leaderboard_page -->|"requests rankings"| node_leaderboard_server
node_leaderboard_server -.->|"reads all-time boards"| node_redis
node_leaderboard_server -->|"reads fallback and recent boards"| node_postgres
node_command_palette -->|"searches users"| node_results_server

click node_test_page "https://github.com/cmmhero/zentype/blob/main/src/app/page.tsx"
click node_typing_ui "https://github.com/cmmhero/zentype/blob/main/src/components/typing/typing-display.tsx"
click node_typing_engine "https://github.com/cmmhero/zentype/blob/main/src/hooks/use-typing-engine.ts"
click node_prompt_server "https://github.com/cmmhero/zentype/blob/main/src/server/prompts.ts"
click node_prompt_utils "https://github.com/cmmhero/zentype/blob/main/src/lib/prompt-utils.ts"
click node_settings_page "https://github.com/cmmhero/zentype/blob/main/src/app/settings/page.tsx"
click node_settings_store "https://github.com/cmmhero/zentype/blob/main/src/stores/settings-store.ts"
click node_settings_sync "https://github.com/cmmhero/zentype/blob/main/src/hooks/use-settings-sync.ts"
click node_auth_server "https://github.com/cmmhero/zentype/blob/main/src/server/auth.ts"
click node_auth_callback "https://github.com/cmmhero/zentype/blob/main/src/app/auth/callback/route.ts"
click node_supabase_client "https://github.com/cmmhero/zentype/blob/main/src/lib/supabase/server.ts"
click node_results_server "https://github.com/cmmhero/zentype/blob/main/src/server/results.ts"
click node_results_store "https://github.com/cmmhero/zentype/blob/main/src/stores/results-store.ts"
click node_gamification "https://github.com/cmmhero/zentype/blob/main/src/server/gamification.ts"
click node_achievements "https://github.com/cmmhero/zentype/blob/main/src/lib/achievements.ts"
click node_profile_page "https://github.com/cmmhero/zentype/blob/main/src/app/profile/page.tsx"
click node_public_profile "https://github.com/cmmhero/zentype/blob/main/src/app/profile/%5Busername%5D/page.tsx"
click node_leaderboard_page "https://github.com/cmmhero/zentype/blob/main/src/app/leaderboard/page.tsx"
click node_leaderboard_server "https://github.com/cmmhero/zentype/blob/main/src/server/leaderboard.ts"
click node_command_palette "https://github.com/cmmhero/zentype/blob/main/src/components/layout/command-palette.tsx"
click node_redis "https://github.com/cmmhero/zentype/blob/main/src/lib/redis.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_test_page,node_typing_ui,node_typing_engine,node_prompt_server,node_prompt_utils toneBlue
class node_results_server,node_results_store,node_gamification,node_achievements,node_profile_page,node_public_profile toneAmber
class node_settings_page,node_settings_store,node_settings_sync,node_auth_server,node_auth_callback toneMint
class node_leaderboard_page,node_leaderboard_server,node_command_palette toneRose
class node_supabase_client,node_supabase,node_redis,node_postgres,node_visitor toneIndigo
```

## Components

### Typing experience

- [Typing page](https://github.com/cmmhero/zentype/blob/main/src/app/page.tsx): `src/app/page.tsx`
- [Typing display](https://github.com/cmmhero/zentype/blob/main/src/components/typing/typing-display.tsx): `src/components/typing/typing-display.tsx`
- [Typing engine](https://github.com/cmmhero/zentype/blob/main/src/hooks/use-typing-engine.ts): `src/hooks/use-typing-engine.ts`
- [Prompt service](https://github.com/cmmhero/zentype/blob/main/src/server/prompts.ts): `src/server/prompts.ts`
- [Prompt utilities](https://github.com/cmmhero/zentype/blob/main/src/lib/prompt-utils.ts): `src/lib/prompt-utils.ts`

### Results and progress

- [Result service](https://github.com/cmmhero/zentype/blob/main/src/server/results.ts): `src/server/results.ts`
- [Guest results](https://github.com/cmmhero/zentype/blob/main/src/stores/results-store.ts): `src/stores/results-store.ts`
- [Progress processing](https://github.com/cmmhero/zentype/blob/main/src/server/gamification.ts): `src/server/gamification.ts`
- [Achievement rules](https://github.com/cmmhero/zentype/blob/main/src/lib/achievements.ts): `src/lib/achievements.ts`
- [Profile dashboard](https://github.com/cmmhero/zentype/blob/main/src/app/profile/page.tsx): `src/app/profile/page.tsx`
- [Public profile](https://github.com/cmmhero/zentype/blob/main/src/app/profile/%5Busername%5D/page.tsx): `src/app/profile/[username]/page.tsx`

### Account and settings

- [Settings](https://github.com/cmmhero/zentype/blob/main/src/app/settings/page.tsx): `src/app/settings/page.tsx`
- [Settings state](https://github.com/cmmhero/zentype/blob/main/src/stores/settings-store.ts): `src/stores/settings-store.ts`
- [Settings sync](https://github.com/cmmhero/zentype/blob/main/src/hooks/use-settings-sync.ts): `src/hooks/use-settings-sync.ts`
- [Auth actions](https://github.com/cmmhero/zentype/blob/main/src/server/auth.ts): `src/server/auth.ts`
- [OAuth callback](https://github.com/cmmhero/zentype/blob/main/src/app/auth/callback/route.ts): `src/app/auth/callback/route.ts`

### Community and discovery

- [Leaderboards](https://github.com/cmmhero/zentype/blob/main/src/app/leaderboard/page.tsx): `src/app/leaderboard/page.tsx`
- [Ranking service](https://github.com/cmmhero/zentype/blob/main/src/server/leaderboard.ts): `src/server/leaderboard.ts`
- [Command palette](https://github.com/cmmhero/zentype/blob/main/src/components/layout/command-palette.tsx): `src/components/layout/command-palette.tsx`

### Persistence services

- [Supabase client](https://github.com/cmmhero/zentype/blob/main/src/lib/supabase/server.ts): `src/lib/supabase/server.ts`
- **Supabase**
- [Redis rankings](https://github.com/cmmhero/zentype/blob/main/src/lib/redis.ts): `src/lib/redis.ts`
- **Postgres**

### Other components

- **Player**

## Connections

- Player → Typing page: starts test
- Typing page → Typing display: renders test
- Typing display → Typing engine: runs engine
- Typing page → Prompt service: requests prompt
- Typing page → Prompt utilities: fallback prompt
- Typing page → Result service: saves result
- Typing page → Guest results: keeps guest results
- Typing page → Progress processing: processes saved result
- Progress processing → Achievement rules: checks progress
- Result service → Supabase client: uses cloud client
- Supabase client → Supabase: reads and writes
- Progress processing → Supabase client: persists progress
- Settings → Settings state: updates settings
- Settings sync → Settings state: syncs settings
- Settings sync → Supabase client: syncs cloud settings
- Auth actions → Supabase client: uses session client
- OAuth callback → Supabase client: exchanges OAuth code
- Profile dashboard → Supabase client: loads account data
- Public profile → Supabase client: loads public data
- Leaderboards → Ranking service: requests rankings
- Ranking service → Redis rankings: reads all-time boards
- Ranking service → Postgres: reads fallback and recent boards
- Command palette → Result service: searches users