# isaluki/wycinanka architecture

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

## Overview

Wycinanka is a Polish-learning web app. Learners choose a course lesson, work through generated exercises and a conversation, then save results that build a spaced-review deck; they can also use review and the app’s reference and practice features. The browser supports guest progress and offline sync, while the Worker provides account-backed progress and optional speech recognition and reminders. Edges are limited to relationships shown in the excerpts, SOURCE INDEX references, or README; unsampled feature internals are represented at their page or directory paths.

Main entry points: [`src/app/App.tsx`](https://github.com/isaluki/wycinanka/blob/main/src/app/App.tsx) (App routing), [`src/worker/index.ts`](https://github.com/isaluki/wycinanka/blob/main/src/worker/index.ts) (Worker router), [`src/app/pages/Lesson.tsx`](https://github.com/isaluki/wycinanka/blob/main/src/app/pages/Lesson.tsx) (Lesson experience), [`src/app/pages/Review.tsx`](https://github.com/isaluki/wycinanka/blob/main/src/app/pages/Review.tsx) (Spaced review)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_learning["Course and lessons"]
  node_course["Course content<br/>[course.ts]"]
  node_lesson["Lesson experience<br/>[Lesson.tsx]"]
  node_exercise["Exercise generation<br/>[exercises.ts]"]
  node_session["Exercise session<br/>[Session.tsx]"]
  node_progress["Progress rules<br/>[engine.ts]"]
end

subgraph group_practice["Practice and references"]
  node_review["Spaced review<br/>[Review.tsx]"]
  node_reading["Graded reading<br/>[Reading.tsx]"]
  node_speaking["Speaking practice<br/>[Speaking.tsx]"]
  node_reference["Learning references<br/>[Grammar.tsx]"]
  node_culture["Culture articles<br/>[Culture.tsx]"]
  node_tools["Learning tools<br/>[Tools.tsx]"]
end

subgraph group_browser["Browser experience"]
  node_app["App routing<br/>[App.tsx]"]
  node_browserstore[("Progress store<br/>[store.ts]")]
  node_api["Browser API client<br/>[api.ts]"]
end

subgraph group_service["Worker services"]
  node_worker["Worker router<br/>[index.ts]"]
  node_auth["Account and sessions<br/>[auth.ts]"]
  node_progressroute["Progress API<br/>[progress.ts]"]
  node_workerstore[("D1 data access<br/>[store.ts]")]
  node_speechroute["Speech recognition<br/>[speech.ts]"]
  node_reminders["Push reminders<br/>[reminders.ts]"]
end

node_learner(("Learner"))

node_learner -->|"uses"| node_app
node_app -->|"routes to"| node_lesson
node_app -->|"routes to"| node_review
node_app -->|"routes to"| node_reading
node_app -->|"routes to"| node_speaking
node_app -->|"routes to"| node_reference
node_app -->|"routes to"| node_culture
node_app -->|"routes to"| node_tools
node_lesson -->|"uses"| node_exercise
node_exercise -->|"draws content"| node_course
node_lesson -->|"runs exercises"| node_session
node_session -->|"records results"| node_progress
node_review -->|"runs review"| node_session
node_review -->|"submits reviews"| node_browserstore
node_progress -->|"gets lesson cards"| node_course
node_learner -->|"reads graded texts"| node_reading
node_learner -->|"practises speech"| node_speaking
node_learner -->|"consults"| node_reference
node_learner -->|"explores"| node_culture
node_learner -->|"uses"| node_tools
node_browserstore -->|"calls"| node_api
node_api -->|"requests"| node_worker
node_worker -->|"routes requests"| node_auth
node_worker -->|"routes requests"| node_progressroute
node_progressroute -->|"uses rules"| node_progress
node_progressroute -->|"loads and saves"| node_workerstore
node_auth -->|"accesses account data"| node_workerstore
node_worker -->|"routes requests"| node_speechroute
node_worker -->|"sends scheduled reminders"| node_reminders
node_learner -->|"may create account"| node_auth
node_learner -.->|"may request transcription"| node_speechroute
node_learner -.->|"may enable reminders"| node_reminders

click node_app "https://github.com/isaluki/wycinanka/blob/main/src/app/App.tsx"
click node_course "https://github.com/isaluki/wycinanka/blob/main/src/content/course.ts"
click node_lesson "https://github.com/isaluki/wycinanka/blob/main/src/app/pages/Lesson.tsx"
click node_exercise "https://github.com/isaluki/wycinanka/blob/main/src/app/lib/exercises.ts"
click node_session "https://github.com/isaluki/wycinanka/blob/main/src/app/components/Session.tsx"
click node_progress "https://github.com/isaluki/wycinanka/blob/main/src/shared/engine.ts"
click node_review "https://github.com/isaluki/wycinanka/blob/main/src/app/pages/Review.tsx"
click node_reading "https://github.com/isaluki/wycinanka/blob/main/src/app/pages/Reading.tsx"
click node_speaking "https://github.com/isaluki/wycinanka/blob/main/src/app/pages/Speaking.tsx"
click node_reference "https://github.com/isaluki/wycinanka/blob/main/src/app/pages/Grammar.tsx"
click node_culture "https://github.com/isaluki/wycinanka/blob/main/src/app/pages/Culture.tsx"
click node_tools "https://github.com/isaluki/wycinanka/blob/main/src/app/pages/Tools.tsx"
click node_browserstore "https://github.com/isaluki/wycinanka/blob/main/src/app/lib/store.ts"
click node_api "https://github.com/isaluki/wycinanka/blob/main/src/app/lib/api.ts"
click node_worker "https://github.com/isaluki/wycinanka/blob/main/src/worker/index.ts"
click node_auth "https://github.com/isaluki/wycinanka/blob/main/src/worker/routes/auth.ts"
click node_progressroute "https://github.com/isaluki/wycinanka/blob/main/src/worker/routes/progress.ts"
click node_workerstore "https://github.com/isaluki/wycinanka/blob/main/src/worker/store.ts"
click node_speechroute "https://github.com/isaluki/wycinanka/blob/main/src/worker/routes/speech.ts"
click node_reminders "https://github.com/isaluki/wycinanka/blob/main/src/worker/reminders.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_course,node_lesson,node_exercise,node_session,node_progress toneBlue
class node_review,node_reading,node_speaking,node_reference,node_culture,node_tools toneAmber
class node_app,node_browserstore,node_api toneMint
class node_worker,node_auth,node_progressroute,node_workerstore,node_speechroute,node_reminders toneRose
class node_learner toneIndigo
```

## Components

### Course and lessons

- [Course content](https://github.com/isaluki/wycinanka/blob/main/src/content/course.ts): `src/content/course.ts`
- [Lesson experience](https://github.com/isaluki/wycinanka/blob/main/src/app/pages/Lesson.tsx): `src/app/pages/Lesson.tsx`
- [Exercise generation](https://github.com/isaluki/wycinanka/blob/main/src/app/lib/exercises.ts): `src/app/lib/exercises.ts`
- [Exercise session](https://github.com/isaluki/wycinanka/blob/main/src/app/components/Session.tsx): `src/app/components/Session.tsx`
- [Progress rules](https://github.com/isaluki/wycinanka/blob/main/src/shared/engine.ts): `src/shared/engine.ts`

### Practice and references

- [Spaced review](https://github.com/isaluki/wycinanka/blob/main/src/app/pages/Review.tsx): `src/app/pages/Review.tsx`
- [Graded reading](https://github.com/isaluki/wycinanka/blob/main/src/app/pages/Reading.tsx): `src/app/pages/Reading.tsx`
- [Speaking practice](https://github.com/isaluki/wycinanka/blob/main/src/app/pages/Speaking.tsx): `src/app/pages/Speaking.tsx`
- [Learning references](https://github.com/isaluki/wycinanka/blob/main/src/app/pages/Grammar.tsx): `src/app/pages/Grammar.tsx`
- [Culture articles](https://github.com/isaluki/wycinanka/blob/main/src/app/pages/Culture.tsx): `src/app/pages/Culture.tsx`
- [Learning tools](https://github.com/isaluki/wycinanka/blob/main/src/app/pages/Tools.tsx): `src/app/pages/Tools.tsx`

### Browser experience

- [App routing](https://github.com/isaluki/wycinanka/blob/main/src/app/App.tsx): `src/app/App.tsx`
- [Progress store](https://github.com/isaluki/wycinanka/blob/main/src/app/lib/store.ts): `src/app/lib/store.ts`
- [Browser API client](https://github.com/isaluki/wycinanka/blob/main/src/app/lib/api.ts): `src/app/lib/api.ts`

### Worker services

- [Worker router](https://github.com/isaluki/wycinanka/blob/main/src/worker/index.ts): `src/worker/index.ts`
- [Account and sessions](https://github.com/isaluki/wycinanka/blob/main/src/worker/routes/auth.ts): `src/worker/routes/auth.ts`
- [Progress API](https://github.com/isaluki/wycinanka/blob/main/src/worker/routes/progress.ts): `src/worker/routes/progress.ts`
- [D1 data access](https://github.com/isaluki/wycinanka/blob/main/src/worker/store.ts): `src/worker/store.ts`
- [Speech recognition](https://github.com/isaluki/wycinanka/blob/main/src/worker/routes/speech.ts): `src/worker/routes/speech.ts`
- [Push reminders](https://github.com/isaluki/wycinanka/blob/main/src/worker/reminders.ts): `src/worker/reminders.ts`

### Other components

- **Learner**

## Connections

- Learner → App routing: uses
- App routing → Lesson experience: routes to (evidence: `src/app/App.tsx`)
- App routing → Spaced review: routes to (evidence: `src/app/App.tsx`)
- App routing → Graded reading: routes to (evidence: `src/app/App.tsx`)
- App routing → Speaking practice: routes to (evidence: `src/app/App.tsx`)
- App routing → Learning references: routes to (evidence: `src/app/App.tsx`)
- App routing → Culture articles: routes to (evidence: `src/app/App.tsx`)
- App routing → Learning tools: routes to (evidence: `src/app/App.tsx`)
- Lesson experience → Exercise generation: uses
- Exercise generation → Course content: draws content (evidence: `src/app/lib/exercises.ts`)
- Lesson experience → Exercise session: runs exercises
- Exercise session → Progress rules: records results
- Spaced review → Exercise session: runs review (evidence: `src/app/pages/Review.tsx`)
- Spaced review → Progress store: submits reviews (evidence: `src/app/pages/Review.tsx`)
- Progress rules → Course content: gets lesson cards (evidence: `src/shared/engine.ts`)
- Learner → Graded reading: reads graded texts
- Learner → Speaking practice: practises speech
- Learner → Learning references: consults
- Learner → Culture articles: explores
- Learner → Learning tools: uses
- Progress store → Browser API client: calls (evidence: `src/app/lib/store.ts`)
- Browser API client → Worker router: requests
- Worker router → Account and sessions: routes requests (evidence: `src/worker/index.ts`)
- Worker router → Progress API: routes requests (evidence: `src/worker/index.ts`)
- Progress API → Progress rules: uses rules (evidence: `src/worker/routes/progress.ts`)
- Progress API → D1 data access: loads and saves (evidence: `src/worker/routes/progress.ts`)
- Account and sessions → D1 data access: accesses account data (evidence: `src/worker/routes/auth.ts`)
- Worker router → Speech recognition: routes requests (evidence: `src/worker/index.ts`)
- Worker router → Push reminders: sends scheduled reminders (evidence: `src/worker/index.ts`)
- Learner → Account and sessions: may create account
- Learner → Speech recognition: may request transcription
- Learner → Push reminders: may enable reminders
