# martinl5/sqlwak architecture

> Architecture diagram of the GitHub repository martinl5/sqlwak, 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/martinl5/sqlwak
- Repository: https://github.com/martinl5/sqlwak

## Overview

SQLwak is a client-side SQL learning game: players choose progressively harder banking and maritime challenges, write and run read-only SQL against a seeded SQLite database, then submit queries for grading and persistent progression. The game shell coordinates the editor, schema and results views, navigation, onboarding, and harbour visuals. Challenge content spans four tiers; progression calculations and persisted game state support ranks, XP, and the ship-themed display. Relationships reflect the README and indexed imports; unsampled validator and UI internals are not inferred beyond those references.

Main entry points: [`src/components/GameProvider.tsx`](https://github.com/martinl5/sqlwak/blob/main/src/components/GameProvider.tsx) (Game shell), [`src/store/useGameStore.ts`](https://github.com/martinl5/sqlwak/blob/main/src/store/useGameStore.ts) (Game state), [`src/data/levels/index.ts`](https://github.com/martinl5/sqlwak/blob/main/src/data/levels/index.ts) (Challenge catalog), [`src/lib/progression.ts`](https://github.com/martinl5/sqlwak/blob/main/src/lib/progression.ts) (XP and rank rules)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Game experience"]
  node_game["Game shell<br/>[GameProvider.tsx]"]
  node_editor["SQL editor<br/>[SQLPanel.tsx]"]
  node_schema["Schema viewer<br/>[SchemaViewer.tsx]"]
  node_results["Results preview<br/>[DataPreview.tsx]"]
  node_navigator["Level navigator<br/>[LevelNavigator.tsx]"]
  node_progressmap["Progress map"]
  node_onboarding["Onboarding"]
  node_levelup["Level-up display<br/>[LevelUpModal.tsx]"]
  node_rankbanner["Rank banner"]
  node_harbour["Harbour visuals<br/>[FlockCanvas.tsx]"]
  node_status["Harbour status<br/>[FlockStatus.tsx]"]
end

subgraph group_challenges["SQL challenges"]
  node_foundational["Foundational levels<br/>[foundational.ts]"]
  node_intermediate["Intermediate levels<br/>[intermediate.ts]"]
  node_advanced["Advanced levels<br/>[advanced.ts]"]
  node_expert["Expert levels<br/>[expert.ts]"]
  node_levelindex["Challenge catalog<br/>[index.ts]"]
end

subgraph group_runtime["Query runtime"]
  node_validator["Query validator<br/>[validator.ts]"]
  node_database[("SQLite database<br/>[db.ts]")]
  node_seed["Bank data seeder<br/>[seed.ts]"]
  node_runner["Read-only runner<br/>[sqlRunner.ts]"]
end

subgraph group_progress["Progression state"]
  node_progression["XP and rank rules<br/>[progression.ts]"]
  node_store["Game state<br/>[useGameStore.ts]"]
  node_types["Shared types<br/>[index.ts]"]
end

node_player(("Player"))

node_player -->|"starts game"| node_game
node_game -->|"initializes"| node_database
node_game -->|"renders"| node_editor
node_game -->|"renders"| node_schema
node_game -->|"renders"| node_results
node_game -->|"renders"| node_navigator
node_game -->|"renders"| node_progressmap
node_game -->|"renders"| node_onboarding
node_game -->|"renders"| node_levelup
node_game -->|"renders"| node_rankbanner
node_game -->|"loads"| node_harbour
node_game -->|"renders"| node_status
node_editor -->|"selects challenge"| node_levelindex
node_editor -->|"executes query"| node_database
node_editor -->|"grades query"| node_validator
node_database -->|"seeds tables"| node_seed
node_database -->|"runs statement"| node_runner
node_database -->|"returns results"| node_editor
node_results -->|"reads results"| node_store
node_levelindex -->|"combines tiers"| node_foundational
node_levelindex -->|"combines tiers"| node_intermediate
node_levelindex -->|"combines tiers"| node_advanced
node_levelindex -->|"combines tiers"| node_expert
node_progression -->|"derives rank rules"| node_levelindex
node_store -->|"calculates XP"| node_progression
node_navigator -->|"updates level"| node_store
node_navigator -->|"lists levels"| node_levelindex
node_progressmap -->|"reads progress"| node_store
node_progressmap -->|"uses ranges"| node_progression
node_levelup -->|"reads progress"| node_store
node_levelup -->|"uses rank rules"| node_progression
node_onboarding -->|"reads state"| node_store
node_onboarding -->|"uses progression"| node_progression
node_harbour -->|"reads fleet"| node_store
node_harbour -->|"uses ship rules"| node_progression
node_status -->|"reads status"| node_store
node_status -->|"uses rank rules"| node_progression

click node_game "https://github.com/martinl5/sqlwak/blob/main/src/components/GameProvider.tsx"
click node_editor "https://github.com/martinl5/sqlwak/blob/main/src/components/SQLPanel.tsx"
click node_schema "https://github.com/martinl5/sqlwak/blob/main/src/components/SchemaViewer.tsx"
click node_results "https://github.com/martinl5/sqlwak/blob/main/src/components/DataPreview.tsx"
click node_navigator "https://github.com/martinl5/sqlwak/blob/main/src/components/LevelNavigator.tsx"
click node_progressmap "https://github.com/martinl5/sqlwak/blob/main/src/components/LevelProgressMap.tsx"
click node_onboarding "https://github.com/martinl5/sqlwak/blob/main/src/components/OnboardingOverlay.tsx"
click node_levelup "https://github.com/martinl5/sqlwak/blob/main/src/components/LevelUpModal.tsx"
click node_rankbanner "https://github.com/martinl5/sqlwak/blob/main/src/components/RankPromotionBanner.tsx"
click node_harbour "https://github.com/martinl5/sqlwak/blob/main/src/components/FlockCanvas.tsx"
click node_status "https://github.com/martinl5/sqlwak/blob/main/src/components/FlockStatus.tsx"
click node_foundational "https://github.com/martinl5/sqlwak/blob/main/src/data/levels/foundational.ts"
click node_intermediate "https://github.com/martinl5/sqlwak/blob/main/src/data/levels/intermediate.ts"
click node_advanced "https://github.com/martinl5/sqlwak/blob/main/src/data/levels/advanced.ts"
click node_expert "https://github.com/martinl5/sqlwak/blob/main/src/data/levels/expert.ts"
click node_levelindex "https://github.com/martinl5/sqlwak/blob/main/src/data/levels/index.ts"
click node_validator "https://github.com/martinl5/sqlwak/blob/main/src/lib/validator.ts"
click node_database "https://github.com/martinl5/sqlwak/blob/main/src/lib/db.ts"
click node_seed "https://github.com/martinl5/sqlwak/blob/main/src/lib/seed.ts"
click node_runner "https://github.com/martinl5/sqlwak/blob/main/src/lib/sqlRunner.ts"
click node_progression "https://github.com/martinl5/sqlwak/blob/main/src/lib/progression.ts"
click node_store "https://github.com/martinl5/sqlwak/blob/main/src/store/useGameStore.ts"
click node_types "https://github.com/martinl5/sqlwak/blob/main/src/types/index.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_game,node_editor,node_schema,node_results,node_navigator,node_progressmap,node_onboarding,node_levelup,node_rankbanner,node_harbour,node_status toneBlue
class node_foundational,node_intermediate,node_advanced,node_expert,node_levelindex toneAmber
class node_validator,node_database,node_seed,node_runner toneMint
class node_progression,node_store,node_types toneRose
class node_player toneIndigo
```

## Components

### Game experience

- [Game shell](https://github.com/martinl5/sqlwak/blob/main/src/components/GameProvider.tsx): `src/components/GameProvider.tsx`
- [SQL editor](https://github.com/martinl5/sqlwak/blob/main/src/components/SQLPanel.tsx): `src/components/SQLPanel.tsx`
- [Schema viewer](https://github.com/martinl5/sqlwak/blob/main/src/components/SchemaViewer.tsx): `src/components/SchemaViewer.tsx`
- [Results preview](https://github.com/martinl5/sqlwak/blob/main/src/components/DataPreview.tsx): `src/components/DataPreview.tsx`
- [Level navigator](https://github.com/martinl5/sqlwak/blob/main/src/components/LevelNavigator.tsx): `src/components/LevelNavigator.tsx`
- [Progress map](https://github.com/martinl5/sqlwak/blob/main/src/components/LevelProgressMap.tsx): `src/components/LevelProgressMap.tsx`
- [Onboarding](https://github.com/martinl5/sqlwak/blob/main/src/components/OnboardingOverlay.tsx): `src/components/OnboardingOverlay.tsx`
- [Level-up display](https://github.com/martinl5/sqlwak/blob/main/src/components/LevelUpModal.tsx): `src/components/LevelUpModal.tsx`
- [Rank banner](https://github.com/martinl5/sqlwak/blob/main/src/components/RankPromotionBanner.tsx): `src/components/RankPromotionBanner.tsx`
- [Harbour visuals](https://github.com/martinl5/sqlwak/blob/main/src/components/FlockCanvas.tsx): `src/components/FlockCanvas.tsx`
- [Harbour status](https://github.com/martinl5/sqlwak/blob/main/src/components/FlockStatus.tsx): `src/components/FlockStatus.tsx`

### SQL challenges

- [Foundational levels](https://github.com/martinl5/sqlwak/blob/main/src/data/levels/foundational.ts): `src/data/levels/foundational.ts`
- [Intermediate levels](https://github.com/martinl5/sqlwak/blob/main/src/data/levels/intermediate.ts): `src/data/levels/intermediate.ts`
- [Advanced levels](https://github.com/martinl5/sqlwak/blob/main/src/data/levels/advanced.ts): `src/data/levels/advanced.ts`
- [Expert levels](https://github.com/martinl5/sqlwak/blob/main/src/data/levels/expert.ts): `src/data/levels/expert.ts`
- [Challenge catalog](https://github.com/martinl5/sqlwak/blob/main/src/data/levels/index.ts): `src/data/levels/index.ts`

### Query runtime

- [Query validator](https://github.com/martinl5/sqlwak/blob/main/src/lib/validator.ts): `src/lib/validator.ts`
- [SQLite database](https://github.com/martinl5/sqlwak/blob/main/src/lib/db.ts): `src/lib/db.ts`
- [Bank data seeder](https://github.com/martinl5/sqlwak/blob/main/src/lib/seed.ts): `src/lib/seed.ts`
- [Read-only runner](https://github.com/martinl5/sqlwak/blob/main/src/lib/sqlRunner.ts): `src/lib/sqlRunner.ts`

### Progression state

- [XP and rank rules](https://github.com/martinl5/sqlwak/blob/main/src/lib/progression.ts): `src/lib/progression.ts`
- [Game state](https://github.com/martinl5/sqlwak/blob/main/src/store/useGameStore.ts): `src/store/useGameStore.ts`
- [Shared types](https://github.com/martinl5/sqlwak/blob/main/src/types/index.ts): `src/types/index.ts`

### Other components

- **Player**

## Connections

- Player → Game shell: starts game (evidence: `README.md`)
- Game shell → SQLite database: initializes (evidence: `src/components/GameProvider.tsx`)
- Game shell → SQL editor: renders (evidence: `src/components/GameProvider.tsx`)
- Game shell → Schema viewer: renders (evidence: `src/components/GameProvider.tsx`)
- Game shell → Results preview: renders (evidence: `src/components/GameProvider.tsx`)
- Game shell → Level navigator: renders (evidence: `src/components/GameProvider.tsx`)
- Game shell → Progress map: renders (evidence: `src/components/GameProvider.tsx`)
- Game shell → Onboarding: renders (evidence: `src/components/GameProvider.tsx`)
- Game shell → Level-up display: renders (evidence: `src/components/GameProvider.tsx`)
- Game shell → Rank banner: renders (evidence: `src/components/GameProvider.tsx`)
- Game shell → Harbour visuals: loads (evidence: `src/components/GameProvider.tsx`)
- Game shell → Harbour status: renders (evidence: `src/components/GameProvider.tsx`)
- SQL editor → Challenge catalog: selects challenge (evidence: `src/components/SQLPanel.tsx`)
- SQL editor → SQLite database: executes query (evidence: `src/components/SQLPanel.tsx`)
- SQL editor → Query validator: grades query (evidence: `src/components/SQLPanel.tsx`)
- SQLite database → Bank data seeder: seeds tables (evidence: `src/lib/db.ts`)
- SQLite database → Read-only runner: runs statement (evidence: `src/lib/db.ts`)
- SQLite database → SQL editor: returns results (evidence: `src/components/SQLPanel.tsx`)
- Results preview → Game state: reads results (evidence: `src/components/DataPreview.tsx`)
- Challenge catalog → Foundational levels: combines tiers (evidence: `src/data/levels/index.ts`)
- Challenge catalog → Intermediate levels: combines tiers (evidence: `src/data/levels/index.ts`)
- Challenge catalog → Advanced levels: combines tiers (evidence: `src/data/levels/index.ts`)
- Challenge catalog → Expert levels: combines tiers (evidence: `src/data/levels/index.ts`)
- XP and rank rules → Challenge catalog: derives rank rules (evidence: `src/lib/progression.ts`)
- Game state → XP and rank rules: calculates XP (evidence: `src/store/useGameStore.ts`)
- Level navigator → Game state: updates level (evidence: `src/components/LevelNavigator.tsx`)
- Level navigator → Challenge catalog: lists levels (evidence: `src/components/LevelNavigator.tsx`)
- Progress map → Game state: reads progress (evidence: `src/components/LevelProgressMap.tsx`)
- Progress map → XP and rank rules: uses ranges (evidence: `src/components/LevelProgressMap.tsx`)
- Level-up display → Game state: reads progress (evidence: `src/components/LevelUpModal.tsx`)
- Level-up display → XP and rank rules: uses rank rules (evidence: `src/components/LevelUpModal.tsx`)
- Onboarding → Game state: reads state (evidence: `src/components/OnboardingOverlay.tsx`)
- Onboarding → XP and rank rules: uses progression (evidence: `src/components/OnboardingOverlay.tsx`)
- Harbour visuals → Game state: reads fleet (evidence: `src/components/FlockCanvas.tsx`)
- Harbour visuals → XP and rank rules: uses ship rules (evidence: `src/components/FlockCanvas.tsx`)
- Harbour status → Game state: reads status (evidence: `src/components/FlockStatus.tsx`)
- Harbour status → XP and rank rules: uses rank rules (evidence: `src/components/FlockStatus.tsx`)
