# cygray/kr40 architecture

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

- Interactive diagram: https://gitdiagram.com/cygray/kr40
- Repository: https://github.com/cygray/kr40

## Overview

KR40 is a mobile-first Korean-learning PWA organized around a 40-day mission. Learners review an adaptive Four-Strands plan, practice through learning and coaching activities, record observable evidence, and consult derived progress and readiness. The browser and MCP both use authenticated server entry points; Firebase-backed repositories persist the audit record and derived read models. OAuth enables remote MCP access. The README documents these capabilities, but many implementations were not sampled, so links among those subsystems are limited to documented or sampled relationships.

Main entry points: [`app/api/learning`](https://github.com/cygray/kr40/tree/main/app/api/learning) (Learning API), [`app/layout.tsx`](https://github.com/cygray/kr40/blob/main/app/layout.tsx) (KR40 PWA), [`src/mcp/tools.ts`](https://github.com/cygray/kr40/blob/main/src/mcp/tools.ts) (MCP tool operations), [`src/lib/firebase/repository.ts`](https://github.com/cygray/kr40/blob/main/src/lib/firebase/repository.ts) (Learning repositories)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Learner experience"]
  node_pwa["KR40 PWA<br/>[layout.tsx]"]
  node_learn["Learning views<br/>[page.tsx]"]
  node_today["Daily plan view<br/>[page.tsx]"]
  node_speak["Speaking practice<br/>[page.tsx]"]
  node_conference["Conference reference<br/>[page.tsx]"]
  node_progress["Progress view<br/>[page.tsx]"]
  node_authui["Sign-in UI"]
end

subgraph group_api["Application endpoints"]
  node_api["Learning API"]
  node_bootstrap["User bootstrap<br/>[route.ts]"]
  node_export["Learner export<br/>[route.ts]"]
  node_mcp["MCP endpoint<br/>[route.ts]"]
  node_oauth["OAuth endpoints"]
end

subgraph group_learning["Learning domain"]
  node_planning["Adaptive planning<br/>[planner.ts]"]
  node_mastery["Mastery and readiness<br/>[mastery.ts]"]
  node_history["History and checkpoints<br/>[history.ts]"]
  node_coaching["Coaching modes<br/>[coaching-modes.ts]"]
end

subgraph group_persistence["Persistence"]
  node_repository["Learning repositories<br/>[repository.ts]"]
  node_coachrepo["Coaching repository"]
  node_firestore[("Firestore")]
end

subgraph group_integrations["External integrations"]
  node_mcpserver["MCP tool registry<br/>[server.ts]"]
  node_mcp_tools["MCP tool operations<br/>[tools.ts]"]
  node_firebaseauth["Firebase Auth<br/>[auth.ts]"]
end

node_learner(("Learner"))
node_google(("Google sign-in"))
node_chatgpt(("MCP client"))

node_learner -->|"uses"| node_pwa
node_pwa -->|"opens"| node_learn
node_pwa -->|"opens"| node_today
node_pwa -->|"opens"| node_speak
node_pwa -->|"opens"| node_conference
node_pwa -->|"opens"| node_progress
node_learner -->|"signs in"| node_authui
node_google -->|"authenticates"| node_firebaseauth
node_authui -->|"uses"| node_firebaseauth
node_learn -->|"requests learning data"| node_api
node_today -->|"requests plan data"| node_api
node_speak -->|"records practice"| node_api
node_conference -->|"requests context"| node_api
node_progress -->|"requests progress"| node_api
node_api -->|"reads and writes"| node_repository
node_api -->|"records coaching"| node_coachrepo
node_api -->|"uses planning rules"| node_planning
node_api -->|"derives progress"| node_mastery
node_api -->|"uses history rules"| node_history
node_api -->|"persists data"| node_firestore
node_bootstrap -->|"seeds user data"| node_firestore
node_export -->|"exports learner data"| node_repository
node_chatgpt -->|"calls tools"| node_mcp
node_mcp -->|"dispatches"| node_mcpserver
node_mcpserver -->|"invokes"| node_mcp_tools
node_mcp_tools -->|"reads and writes"| node_repository
node_mcp_tools -->|"records coaching"| node_coachrepo
node_mcp_tools -->|"uses planning rules"| node_planning
node_mcp_tools -->|"derives progress"| node_mastery
node_mcp_tools -->|"persists data"| node_firestore
node_chatgpt -.->|"authorizes"| node_oauth
node_oauth -.->|"stores OAuth state"| node_firestore

click node_pwa "https://github.com/cygray/kr40/blob/main/app/layout.tsx"
click node_learn "https://github.com/cygray/kr40/blob/main/app/learn/page.tsx"
click node_today "https://github.com/cygray/kr40/blob/main/app/today/page.tsx"
click node_speak "https://github.com/cygray/kr40/blob/main/app/speak/page.tsx"
click node_conference "https://github.com/cygray/kr40/blob/main/app/conference/page.tsx"
click node_progress "https://github.com/cygray/kr40/blob/main/app/progress/page.tsx"
click node_authui "https://github.com/cygray/kr40/blob/main/components/kr40-auth-provider.tsx"
click node_api "https://github.com/cygray/kr40/tree/main/app/api/learning"
click node_bootstrap "https://github.com/cygray/kr40/blob/main/app/api/bootstrap/route.ts"
click node_export "https://github.com/cygray/kr40/blob/main/app/api/export/route.ts"
click node_mcp "https://github.com/cygray/kr40/blob/main/app/mcp/route.ts"
click node_oauth "https://github.com/cygray/kr40/tree/main/src/server/oauth"
click node_planning "https://github.com/cygray/kr40/blob/main/src/domain/planner.ts"
click node_mastery "https://github.com/cygray/kr40/blob/main/src/domain/mastery.ts"
click node_history "https://github.com/cygray/kr40/blob/main/src/domain/history.ts"
click node_coaching "https://github.com/cygray/kr40/blob/main/src/domain/coaching-modes.ts"
click node_mcpserver "https://github.com/cygray/kr40/blob/main/src/mcp/server.ts"
click node_mcp_tools "https://github.com/cygray/kr40/blob/main/src/mcp/tools.ts"
click node_repository "https://github.com/cygray/kr40/blob/main/src/lib/firebase/repository.ts"
click node_coachrepo "https://github.com/cygray/kr40/blob/main/src/lib/firebase/coach-repository.ts"
click node_firebaseauth "https://github.com/cygray/kr40/blob/main/src/lib/firebase/auth.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_pwa,node_learn,node_today,node_speak,node_conference,node_progress,node_authui,node_chatgpt toneBlue
class node_api,node_bootstrap,node_export,node_mcp,node_oauth toneAmber
class node_planning,node_mastery,node_history,node_coaching toneMint
class node_repository,node_coachrepo,node_firestore toneRose
class node_mcpserver,node_mcp_tools,node_firebaseauth,node_learner,node_google toneIndigo
```

## Components

### Learner experience

- [KR40 PWA](https://github.com/cygray/kr40/blob/main/app/layout.tsx): `app/layout.tsx`
- [Learning views](https://github.com/cygray/kr40/blob/main/app/learn/page.tsx): `app/learn/page.tsx`
- [Daily plan view](https://github.com/cygray/kr40/blob/main/app/today/page.tsx): `app/today/page.tsx`
- [Speaking practice](https://github.com/cygray/kr40/blob/main/app/speak/page.tsx): `app/speak/page.tsx`
- [Conference reference](https://github.com/cygray/kr40/blob/main/app/conference/page.tsx): `app/conference/page.tsx`
- [Progress view](https://github.com/cygray/kr40/blob/main/app/progress/page.tsx): `app/progress/page.tsx`
- [Sign-in UI](https://github.com/cygray/kr40/blob/main/components/kr40-auth-provider.tsx): `components/kr40-auth-provider.tsx`

### Application endpoints

- [Learning API](https://github.com/cygray/kr40/tree/main/app/api/learning): `app/api/learning`
- [User bootstrap](https://github.com/cygray/kr40/blob/main/app/api/bootstrap/route.ts): `app/api/bootstrap/route.ts`
- [Learner export](https://github.com/cygray/kr40/blob/main/app/api/export/route.ts): `app/api/export/route.ts`
- [MCP endpoint](https://github.com/cygray/kr40/blob/main/app/mcp/route.ts): `app/mcp/route.ts`
- [OAuth endpoints](https://github.com/cygray/kr40/tree/main/src/server/oauth): `src/server/oauth`

### Learning domain

- [Adaptive planning](https://github.com/cygray/kr40/blob/main/src/domain/planner.ts): `src/domain/planner.ts`
- [Mastery and readiness](https://github.com/cygray/kr40/blob/main/src/domain/mastery.ts): `src/domain/mastery.ts`
- [History and checkpoints](https://github.com/cygray/kr40/blob/main/src/domain/history.ts): `src/domain/history.ts`
- [Coaching modes](https://github.com/cygray/kr40/blob/main/src/domain/coaching-modes.ts): `src/domain/coaching-modes.ts`

### Persistence

- [Learning repositories](https://github.com/cygray/kr40/blob/main/src/lib/firebase/repository.ts): `src/lib/firebase/repository.ts`
- [Coaching repository](https://github.com/cygray/kr40/blob/main/src/lib/firebase/coach-repository.ts): `src/lib/firebase/coach-repository.ts`
- **Firestore**

### External integrations

- [MCP tool registry](https://github.com/cygray/kr40/blob/main/src/mcp/server.ts): `src/mcp/server.ts`
- [MCP tool operations](https://github.com/cygray/kr40/blob/main/src/mcp/tools.ts): `src/mcp/tools.ts`
- [Firebase Auth](https://github.com/cygray/kr40/blob/main/src/lib/firebase/auth.ts): `src/lib/firebase/auth.ts`

### Other components

- **Learner**
- **Google sign-in**
- **MCP client**

## Connections

- Learner → KR40 PWA: uses
- KR40 PWA → Learning views: opens
- KR40 PWA → Daily plan view: opens
- KR40 PWA → Speaking practice: opens
- KR40 PWA → Conference reference: opens
- KR40 PWA → Progress view: opens
- Learner → Sign-in UI: signs in
- Google sign-in → Firebase Auth: authenticates
- Sign-in UI → Firebase Auth: uses
- Learning views → Learning API: requests learning data
- Daily plan view → Learning API: requests plan data
- Speaking practice → Learning API: records practice
- Conference reference → Learning API: requests context
- Progress view → Learning API: requests progress
- Learning API → Learning repositories: reads and writes
- Learning API → Coaching repository: records coaching
- Learning API → Adaptive planning: uses planning rules
- Learning API → Mastery and readiness: derives progress
- Learning API → History and checkpoints: uses history rules
- Learning API → Firestore: persists data
- User bootstrap → Firestore: seeds user data
- Learner export → Learning repositories: exports learner data
- MCP client → MCP endpoint: calls tools
- MCP endpoint → MCP tool registry: dispatches
- MCP tool registry → MCP tool operations: invokes
- MCP tool operations → Learning repositories: reads and writes
- MCP tool operations → Coaching repository: records coaching
- MCP tool operations → Adaptive planning: uses planning rules
- MCP tool operations → Mastery and readiness: derives progress
- MCP tool operations → Firestore: persists data
- MCP client → OAuth endpoints: authorizes
- OAuth endpoints → Firestore: stores OAuth state