# pondag5/cyberteacher architecture

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

- Interactive diagram: https://gitdiagram.com/pondag5/cyberteacher
- Repository: https://github.com/pondag5/cyberteacher

## Overview

CyberTeacher is an interactive cybersecurity-learning product: learners use its CLI or PWA/API to study, practice labs and quizzes, and progress through narrative risk mechanics. The graph preserves those distinct learning, practice, story, and progress capabilities plus its knowledge and long-term learning-memory layers. Source coverage is based on the README, tree, SOURCE INDEX, and shown excerpts; unsampled capabilities are included only where documented, and edges are limited to relationships those sources support.

Main entry points: [`api_server.py`](https://github.com/pondag5/cyberteacher/blob/main/api_server.py) (REST and WS API), [`main.py`](https://github.com/pondag5/cyberteacher/blob/main/main.py) (CLI session), [`state.py`](https://github.com/pondag5/cyberteacher/blob/main/state.py) (Learner state), [`services/learning_memory_service.py`](https://github.com/pondag5/cyberteacher/blob/main/services/learning_memory_service.py) (Learning memory)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_cli["CLI session<br/>[main.py]"]
  node_pwa["PWA client<br/>[app.js]"]
end

subgraph group_learning["Learning and practice"]
  node_courses["Course management<br/>[course_manager.py]"]
  node_pedagogy["Teaching flow<br/>[pedagogy.py]"]
  node_quiz["Quizzes<br/>[quiz.py]"]
  node_practice["Cyber labs<br/>[practice.py]"]
  node_code_review["Code review<br/>[code_review_v2.py]"]
end

subgraph group_world["Story and simulation"]
  node_story["Story mode<br/>[story_mode.py]"]
  node_event_engine["Narrative events<br/>[event_engine.py]"]
  node_risk["Risk mechanics<br/>[risk.py]"]
  node_cyberpsychosis["Cyberpsychosis<br/>[cyberpsychosis.py]"]
  node_world_state["World state<br/>[world_state.py]"]
end

subgraph group_memory["Learner state"]
  node_app_state["Learner state<br/>[state.py]"]
  node_database[("Persistent data<br/>[db.py]")]
  node_learning_memory["Learning memory"]
  node_personality["Teacher personality<br/>[personality.py]"]
end

subgraph group_platform["Knowledge and API"]
  node_api["REST and WS API<br/>[api_server.py]"]
  node_handlers["Feature handlers"]
  node_knowledge["Knowledge retrieval<br/>[knowledge.py]"]
  node_config["LLM configuration<br/>[config.py]"]
  node_routes["Route modules<br/>[__init__.py]"]
end

node_learner(("Learner"))

node_learner -->|"uses"| node_cli
node_learner -->|"uses"| node_pwa
node_cli -->|"starts or stops"| node_api
node_pwa -.->|"uses API and chat"| node_api
node_api -->|"uses"| node_app_state
node_api -->|"routes requests"| node_handlers
node_api -->|"registers routes"| node_story
node_api -->|"registers routes"| node_risk
node_api -->|"uses"| node_learning_memory
node_api -->|"uses"| node_personality
node_cli -->|"uses"| node_app_state
node_cli -->|"queries"| node_knowledge
node_cli -->|"uses"| node_pedagogy
node_cli -->|"queries lab status"| node_practice
node_event_engine -->|"reads and updates"| node_app_state
node_event_engine -->|"reads level"| node_cyberpsychosis
node_routes -->|"serves risk mechanics"| node_risk
node_app_state -.->|"persists learning events"| node_database
node_learning_memory -->|"stores and retrieves events"| node_database
node_app_state -->|"provides review scheduling"| node_learning_memory
node_courses -.->|"tracks course progress"| node_learner
node_config -.->|"configures retrieval"| node_knowledge
node_knowledge -.->|"supplies study context"| node_pedagogy

click node_cli "https://github.com/pondag5/cyberteacher/blob/main/main.py"
click node_pwa "https://github.com/pondag5/cyberteacher/blob/main/static/js/app.js"
click node_api "https://github.com/pondag5/cyberteacher/blob/main/api_server.py"
click node_handlers "https://github.com/pondag5/cyberteacher/tree/main/handlers"
click node_courses "https://github.com/pondag5/cyberteacher/blob/main/course_manager.py"
click node_pedagogy "https://github.com/pondag5/cyberteacher/blob/main/pedagogy.py"
click node_quiz "https://github.com/pondag5/cyberteacher/blob/main/handlers/quiz.py"
click node_practice "https://github.com/pondag5/cyberteacher/blob/main/practice.py"
click node_code_review "https://github.com/pondag5/cyberteacher/blob/main/handlers/code_review_v2.py"
click node_knowledge "https://github.com/pondag5/cyberteacher/blob/main/knowledge.py"
click node_story "https://github.com/pondag5/cyberteacher/blob/main/story_mode.py"
click node_event_engine "https://github.com/pondag5/cyberteacher/blob/main/handlers/event_engine.py"
click node_risk "https://github.com/pondag5/cyberteacher/blob/main/routes/risk.py"
click node_cyberpsychosis "https://github.com/pondag5/cyberteacher/blob/main/cyberpsychosis.py"
click node_world_state "https://github.com/pondag5/cyberteacher/blob/main/world_state.py"
click node_app_state "https://github.com/pondag5/cyberteacher/blob/main/state.py"
click node_database "https://github.com/pondag5/cyberteacher/blob/main/db.py"
click node_learning_memory "https://github.com/pondag5/cyberteacher/blob/main/services/learning_memory_service.py"
click node_personality "https://github.com/pondag5/cyberteacher/blob/main/personality.py"
click node_config "https://github.com/pondag5/cyberteacher/blob/main/config.py"
click node_routes "https://github.com/pondag5/cyberteacher/blob/main/routes/__init__.py"

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_cli,node_pwa toneBlue
class node_courses,node_pedagogy,node_quiz,node_practice,node_code_review toneAmber
class node_story,node_event_engine,node_risk,node_cyberpsychosis,node_world_state toneMint
class node_app_state,node_database,node_learning_memory,node_personality toneRose
class node_api,node_handlers,node_knowledge,node_config,node_routes,node_learner toneIndigo
```

## Components

### User interfaces

- [CLI session](https://github.com/pondag5/cyberteacher/blob/main/main.py): `main.py`
- [PWA client](https://github.com/pondag5/cyberteacher/blob/main/static/js/app.js): `static/js/app.js`

### Learning and practice

- [Course management](https://github.com/pondag5/cyberteacher/blob/main/course_manager.py): `course_manager.py`
- [Teaching flow](https://github.com/pondag5/cyberteacher/blob/main/pedagogy.py): `pedagogy.py`
- [Quizzes](https://github.com/pondag5/cyberteacher/blob/main/handlers/quiz.py): `handlers/quiz.py`
- [Cyber labs](https://github.com/pondag5/cyberteacher/blob/main/practice.py): `practice.py`
- [Code review](https://github.com/pondag5/cyberteacher/blob/main/handlers/code_review_v2.py): `handlers/code_review_v2.py`

### Story and simulation

- [Story mode](https://github.com/pondag5/cyberteacher/blob/main/story_mode.py): `story_mode.py`
- [Narrative events](https://github.com/pondag5/cyberteacher/blob/main/handlers/event_engine.py): `handlers/event_engine.py`
- [Risk mechanics](https://github.com/pondag5/cyberteacher/blob/main/routes/risk.py): `routes/risk.py`
- [Cyberpsychosis](https://github.com/pondag5/cyberteacher/blob/main/cyberpsychosis.py): `cyberpsychosis.py`
- [World state](https://github.com/pondag5/cyberteacher/blob/main/world_state.py): `world_state.py`

### Learner state

- [Learner state](https://github.com/pondag5/cyberteacher/blob/main/state.py): `state.py`
- [Persistent data](https://github.com/pondag5/cyberteacher/blob/main/db.py): `db.py`
- [Learning memory](https://github.com/pondag5/cyberteacher/blob/main/services/learning_memory_service.py): `services/learning_memory_service.py`
- [Teacher personality](https://github.com/pondag5/cyberteacher/blob/main/personality.py): `personality.py`

### Knowledge and API

- [REST and WS API](https://github.com/pondag5/cyberteacher/blob/main/api_server.py): `api_server.py`
- [Feature handlers](https://github.com/pondag5/cyberteacher/tree/main/handlers): `handlers`
- [Knowledge retrieval](https://github.com/pondag5/cyberteacher/blob/main/knowledge.py): `knowledge.py`
- [LLM configuration](https://github.com/pondag5/cyberteacher/blob/main/config.py): `config.py`
- [Route modules](https://github.com/pondag5/cyberteacher/blob/main/routes/__init__.py): `routes/__init__.py`

### Other components

- **Learner**

## Connections

- Learner → CLI session: uses (evidence: `README.md`)
- Learner → PWA client: uses (evidence: `README.md`)
- CLI session → REST and WS API: starts or stops
- PWA client → REST and WS API: uses API and chat (evidence: `README.md`)
- REST and WS API → Learner state: uses (evidence: `api_server.py`)
- REST and WS API → Feature handlers: routes requests (evidence: `api_server.py`)
- REST and WS API → Story mode: registers routes (evidence: `api_server.py`)
- REST and WS API → Risk mechanics: registers routes (evidence: `api_server.py`)
- REST and WS API → Learning memory: uses (evidence: `README.md`)
- REST and WS API → Teacher personality: uses (evidence: `README.md`)
- CLI session → Learner state: uses (evidence: `main.py`)
- CLI session → Knowledge retrieval: queries (evidence: `main.py`)
- CLI session → Teaching flow: uses (evidence: `main.py`)
- CLI session → Cyber labs: queries lab status (evidence: `main.py`)
- Narrative events → Learner state: reads and updates (evidence: `handlers/event_engine.py`)
- Narrative events → Cyberpsychosis: reads level (evidence: `handlers/event_engine.py`)
- Route modules → Risk mechanics: serves risk mechanics (evidence: `routes/risk.py`)
- Learner state → Persistent data: persists learning events
- Learning memory → Persistent data: stores and retrieves events (evidence: `services/learning_memory_service.py`)
- Learner state → Learning memory: provides review scheduling (evidence: `state.py`)
- Course management → Learner: tracks course progress
- LLM configuration → Knowledge retrieval: configures retrieval
- Knowledge retrieval → Teaching flow: supplies study context
