# devlunaris/ap02 architecture

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

- Interactive diagram: https://gitdiagram.com/devlunaris/ap02
- Repository: https://github.com/devlunaris/ap02

## Overview

AP2 Lernhub is a self-hosted IHK exam-preparation platform centered on finding topics, studying their MDX lessons, and running interactive exercises. Learners can also browse a focus list or mixed exercise pool, search topics, and track status and notes locally. The three exercise engines cover stepwise German pseudocode tracing, browser-side SQLite, and C# execution through a server-side runner proxy. The graph follows documented capabilities and sampled API, search, progress, and parser code; unsampled page wiring is represented only where the README supports the relationship.

Main entry points: [`lib/content/topics.ts`](https://github.com/devlunaris/ap02/blob/main/lib/content/topics.ts) (Topic content), [`components/mdx/index.tsx`](https://github.com/devlunaris/ap02/blob/main/components/mdx/index.tsx) (Exercise widgets), [`components/mdx/pseudocode-tracer.tsx`](https://github.com/devlunaris/ap02/blob/main/components/mdx/pseudocode-tracer.tsx) (Pseudocode tracer), [`components/mdx/sql-exercise.tsx`](https://github.com/devlunaris/ap02/blob/main/components/mdx/sql-exercise.tsx) (SQL exercise)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_learning["Learning content"]
  node_home["Home<br/>[page.tsx]"]
  node_topic_index["Topic index<br/>[page.tsx]"]
  node_topic_page["Topic lesson<br/>[page.tsx]"]
  node_category_page["Category browse<br/>[page.tsx]"]
  node_content["Topic content<br/>[topics.ts]"]
  node_mdx["MDX renderer<br/>[mdx.tsx]"]
end

subgraph group_practice["Interactive practice"]
  node_exercise_pool["Exercise pool<br/>[exercise-pool.tsx]"]
  node_mdx_widgets["Exercise widgets<br/>[index.tsx]"]
end

subgraph group_engines["Execution engines"]
  node_pseudo_ui["Pseudocode tracer"]
  node_pseudo_parse["Pseudocode parser<br/>[parser.ts]"]
  node_pseudo_tokens["Pseudocode tokenizer<br/>[tokenizer.ts]"]
  node_pseudo_run["Pseudocode interpreter<br/>[interpreter.ts]"]
  node_sql_ui["SQL exercise<br/>[sql-exercise.tsx]"]
  node_sql_runner["SQLite engine<br/>[runner.ts]"]
  node_sql_compare["SQL comparison<br/>[compare.ts]"]
  node_csharp_ui["C&#35; exercise"]
  node_runner_client["Runner client<br/>[client.ts]"]
end

subgraph group_progress["Progress and planning"]
  node_progress_ui["Progress controls<br/>[progress-panel.tsx]"]
  node_progress_api["Progress hooks<br/>[index.ts]"]
  node_progress_store[("Browser progress<br/>[store.ts]")]
  node_focus["Focus list<br/>[focus-list.tsx]"]
  node_exam["Exam countdown<br/>[exam-countdown.tsx]"]
  node_exam_config["Exam date<br/>[exam.ts]"]
end

subgraph group_platform["Platform services"]
  node_run_api["Run endpoint<br/>[route.ts]"]
  node_runner["Runner adapter<br/>[index.ts]"]
  node_piston["Piston service"]
  node_search_ui["Search dialog<br/>[search-dialog.tsx]"]
  node_search_api["Search endpoint<br/>[route.ts]"]
  node_search_builder["Search index builder<br/>[index-builder.ts]"]
  node_search["Search engine<br/>[search.ts]"]
end

node_learner(("Learner"))

node_learner -->|"opens"| node_home
node_learner -->|"browses"| node_topic_index
node_learner -->|"browses"| node_category_page
node_home -->|"shows topics"| node_content
node_topic_index -->|"lists topics"| node_content
node_category_page -->|"lists topics"| node_content
node_topic_page -->|"loads lesson"| node_content
node_topic_page -->|"renders MDX"| node_mdx
node_mdx -->|"uses components"| node_mdx_widgets
node_mdx_widgets -->|"renders"| node_pseudo_ui
node_mdx_widgets -->|"renders"| node_sql_ui
node_mdx_widgets -->|"renders"| node_csharp_ui
node_pseudo_ui -->|"parses code"| node_pseudo_parse
node_pseudo_parse -->|"tokenizes"| node_pseudo_tokens
node_pseudo_ui -->|"traces code"| node_pseudo_run
node_sql_ui -->|"executes SQL"| node_sql_runner
node_sql_ui -->|"checks results"| node_sql_compare
node_csharp_ui -->|"submits code"| node_runner_client
node_runner_client -->|"posts code"| node_run_api
node_run_api -->|"dispatches"| node_runner
node_runner -.->|"runs remotely"| node_piston
node_learner -->|"practises"| node_exercise_pool
node_exercise_pool -->|"collects exercises"| node_content
node_learner -->|"searches"| node_search_ui
node_search_ui -->|"fetches index"| node_search_api
node_search_api -->|"builds response"| node_search_builder
node_search_ui -->|"queries"| node_search
node_learner -->|"tracks learning"| node_progress_ui
node_progress_ui -->|"updates status"| node_progress_api
node_progress_api -->|"reads and writes"| node_progress_store
node_learner -->|"follows focus"| node_focus
node_focus -->|"uses topic list"| node_content
node_learner -->|"checks date"| node_exam
node_exam -->|"reads date"| node_exam_config

click node_home "https://github.com/devlunaris/ap02/blob/main/app/page.tsx"
click node_topic_index "https://github.com/devlunaris/ap02/blob/main/app/themen/page.tsx"
click node_topic_page "https://github.com/devlunaris/ap02/blob/main/app/thema/%5Bslug%5D/page.tsx"
click node_category_page "https://github.com/devlunaris/ap02/blob/main/app/kategorie/%5Bslug%5D/page.tsx"
click node_content "https://github.com/devlunaris/ap02/blob/main/lib/content/topics.ts"
click node_mdx "https://github.com/devlunaris/ap02/blob/main/lib/content/mdx.tsx"
click node_exercise_pool "https://github.com/devlunaris/ap02/blob/main/components/exercise-pool.tsx"
click node_mdx_widgets "https://github.com/devlunaris/ap02/blob/main/components/mdx/index.tsx"
click node_pseudo_ui "https://github.com/devlunaris/ap02/blob/main/components/mdx/pseudocode-tracer.tsx"
click node_pseudo_parse "https://github.com/devlunaris/ap02/blob/main/lib/pseudocode/parser.ts"
click node_pseudo_tokens "https://github.com/devlunaris/ap02/blob/main/lib/pseudocode/tokenizer.ts"
click node_pseudo_run "https://github.com/devlunaris/ap02/blob/main/lib/pseudocode/interpreter.ts"
click node_sql_ui "https://github.com/devlunaris/ap02/blob/main/components/mdx/sql-exercise.tsx"
click node_sql_runner "https://github.com/devlunaris/ap02/blob/main/lib/sql/runner.ts"
click node_sql_compare "https://github.com/devlunaris/ap02/blob/main/lib/sql/compare.ts"
click node_csharp_ui "https://github.com/devlunaris/ap02/blob/main/components/mdx/csharp-exercise.tsx"
click node_runner_client "https://github.com/devlunaris/ap02/blob/main/lib/runner/client.ts"
click node_run_api "https://github.com/devlunaris/ap02/blob/main/app/api/run/route.ts"
click node_runner "https://github.com/devlunaris/ap02/blob/main/lib/runner/index.ts"
click node_search_ui "https://github.com/devlunaris/ap02/blob/main/components/search/search-dialog.tsx"
click node_search_api "https://github.com/devlunaris/ap02/blob/main/app/api/suche/route.ts"
click node_search_builder "https://github.com/devlunaris/ap02/blob/main/lib/search/index-builder.ts"
click node_search "https://github.com/devlunaris/ap02/blob/main/lib/search/search.ts"
click node_progress_ui "https://github.com/devlunaris/ap02/blob/main/components/progress/progress-panel.tsx"
click node_progress_api "https://github.com/devlunaris/ap02/blob/main/lib/progress/index.ts"
click node_progress_store "https://github.com/devlunaris/ap02/blob/main/lib/progress/store.ts"
click node_focus "https://github.com/devlunaris/ap02/blob/main/components/focus-list.tsx"
click node_exam "https://github.com/devlunaris/ap02/blob/main/components/exam-countdown.tsx"
click node_exam_config "https://github.com/devlunaris/ap02/blob/main/config/exam.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_home,node_topic_index,node_topic_page,node_category_page,node_content,node_mdx toneBlue
class node_exercise_pool,node_mdx_widgets toneAmber
class node_pseudo_ui,node_pseudo_parse,node_pseudo_tokens,node_pseudo_run,node_sql_ui,node_sql_runner,node_sql_compare,node_csharp_ui,node_runner_client toneMint
class node_progress_ui,node_progress_api,node_progress_store,node_focus,node_exam,node_exam_config toneRose
class node_run_api,node_runner,node_piston,node_search_ui,node_search_api,node_search_builder,node_search,node_learner toneIndigo
```

## Components

### Learning content

- [Home](https://github.com/devlunaris/ap02/blob/main/app/page.tsx): `app/page.tsx`
- [Topic index](https://github.com/devlunaris/ap02/blob/main/app/themen/page.tsx): `app/themen/page.tsx`
- [Topic lesson](https://github.com/devlunaris/ap02/blob/main/app/thema/%5Bslug%5D/page.tsx): `app/thema/[slug]/page.tsx`
- [Category browse](https://github.com/devlunaris/ap02/blob/main/app/kategorie/%5Bslug%5D/page.tsx): `app/kategorie/[slug]/page.tsx`
- [Topic content](https://github.com/devlunaris/ap02/blob/main/lib/content/topics.ts): `lib/content/topics.ts`
- [MDX renderer](https://github.com/devlunaris/ap02/blob/main/lib/content/mdx.tsx): `lib/content/mdx.tsx`

### Interactive practice

- [Exercise pool](https://github.com/devlunaris/ap02/blob/main/components/exercise-pool.tsx): `components/exercise-pool.tsx`
- [Exercise widgets](https://github.com/devlunaris/ap02/blob/main/components/mdx/index.tsx): `components/mdx/index.tsx`

### Execution engines

- [Pseudocode tracer](https://github.com/devlunaris/ap02/blob/main/components/mdx/pseudocode-tracer.tsx): `components/mdx/pseudocode-tracer.tsx`
- [Pseudocode parser](https://github.com/devlunaris/ap02/blob/main/lib/pseudocode/parser.ts): `lib/pseudocode/parser.ts`
- [Pseudocode tokenizer](https://github.com/devlunaris/ap02/blob/main/lib/pseudocode/tokenizer.ts): `lib/pseudocode/tokenizer.ts`
- [Pseudocode interpreter](https://github.com/devlunaris/ap02/blob/main/lib/pseudocode/interpreter.ts): `lib/pseudocode/interpreter.ts`
- [SQL exercise](https://github.com/devlunaris/ap02/blob/main/components/mdx/sql-exercise.tsx): `components/mdx/sql-exercise.tsx`
- [SQLite engine](https://github.com/devlunaris/ap02/blob/main/lib/sql/runner.ts): `lib/sql/runner.ts`
- [SQL comparison](https://github.com/devlunaris/ap02/blob/main/lib/sql/compare.ts): `lib/sql/compare.ts`
- [C# exercise](https://github.com/devlunaris/ap02/blob/main/components/mdx/csharp-exercise.tsx): `components/mdx/csharp-exercise.tsx`
- [Runner client](https://github.com/devlunaris/ap02/blob/main/lib/runner/client.ts): `lib/runner/client.ts`

### Progress and planning

- [Progress controls](https://github.com/devlunaris/ap02/blob/main/components/progress/progress-panel.tsx): `components/progress/progress-panel.tsx`
- [Progress hooks](https://github.com/devlunaris/ap02/blob/main/lib/progress/index.ts): `lib/progress/index.ts`
- [Browser progress](https://github.com/devlunaris/ap02/blob/main/lib/progress/store.ts): `lib/progress/store.ts`
- [Focus list](https://github.com/devlunaris/ap02/blob/main/components/focus-list.tsx): `components/focus-list.tsx`
- [Exam countdown](https://github.com/devlunaris/ap02/blob/main/components/exam-countdown.tsx): `components/exam-countdown.tsx`
- [Exam date](https://github.com/devlunaris/ap02/blob/main/config/exam.ts): `config/exam.ts`

### Platform services

- [Run endpoint](https://github.com/devlunaris/ap02/blob/main/app/api/run/route.ts): `app/api/run/route.ts`
- [Runner adapter](https://github.com/devlunaris/ap02/blob/main/lib/runner/index.ts): `lib/runner/index.ts`
- **Piston service**
- [Search dialog](https://github.com/devlunaris/ap02/blob/main/components/search/search-dialog.tsx): `components/search/search-dialog.tsx`
- [Search endpoint](https://github.com/devlunaris/ap02/blob/main/app/api/suche/route.ts): `app/api/suche/route.ts`
- [Search index builder](https://github.com/devlunaris/ap02/blob/main/lib/search/index-builder.ts): `lib/search/index-builder.ts`
- [Search engine](https://github.com/devlunaris/ap02/blob/main/lib/search/search.ts): `lib/search/search.ts`

### Other components

- **Learner**

## Connections

- Learner → Home: opens
- Learner → Topic index: browses
- Learner → Category browse: browses
- Home → Topic content: shows topics
- Topic index → Topic content: lists topics
- Category browse → Topic content: lists topics
- Topic lesson → Topic content: loads lesson
- Topic lesson → MDX renderer: renders MDX
- MDX renderer → Exercise widgets: uses components
- Exercise widgets → Pseudocode tracer: renders
- Exercise widgets → SQL exercise: renders
- Exercise widgets → C# exercise: renders
- Pseudocode tracer → Pseudocode parser: parses code
- Pseudocode parser → Pseudocode tokenizer: tokenizes
- Pseudocode tracer → Pseudocode interpreter: traces code
- SQL exercise → SQLite engine: executes SQL
- SQL exercise → SQL comparison: checks results
- C# exercise → Runner client: submits code
- Runner client → Run endpoint: posts code
- Run endpoint → Runner adapter: dispatches
- Runner adapter → Piston service: runs remotely
- Learner → Exercise pool: practises
- Exercise pool → Topic content: collects exercises
- Learner → Search dialog: searches
- Search dialog → Search endpoint: fetches index
- Search endpoint → Search index builder: builds response
- Search dialog → Search engine: queries
- Learner → Progress controls: tracks learning
- Progress controls → Progress hooks: updates status
- Progress hooks → Browser progress: reads and writes
- Learner → Focus list: follows focus
- Focus list → Topic content: uses topic list
- Learner → Exam countdown: checks date
- Exam countdown → Exam date: reads date