# steppetech1/quack architecture

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

## Overview

Quack! connects university-program selection with personalized exam preparation, using deterministic rules as the source of truth and language models for conversation and explanations. The learner chats to build a profile, reviews ranked programs, saves choices, then diagnoses and practices exam skills; task evidence updates knowledge, sets, forecasts, and the Quack change feed. The graph preserves these documented capabilities and the event-driven rules layer. Some subsystem links are documented only at README level; unsampled implementation details are not inferred.

Main entry points: [`frontend/src/components/prep/PrepView.tsx`](https://github.com/steppetech1/quack/blob/main/frontend/src/components/prep/PrepView.tsx) (Preparation interface), [`backend/app/db/repo/profiles.py`](https://github.com/steppetech1/quack/blob/main/backend/app/db/repo/profiles.py) (Profile and programs), [`backend/app/knowledge/hlr.py`](https://github.com/steppetech1/quack/blob/main/backend/app/knowledge/hlr.py) (Knowledge model), [`backend/app/main.py`](https://github.com/steppetech1/quack/blob/main/backend/app/main.py) (HTTP API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Learner experience"]
  node_web["Web app<br/>[page.tsx]"]
  node_choice_ui["Choice interface<br/>[ChoiceApp.tsx]"]
  node_prep_ui["Preparation interface<br/>[PrepView.tsx]"]
  node_quack_ui["Change feed<br/>[standing.ts]"]
end

subgraph group_orchestration["API and events"]
  node_api["HTTP API<br/>[main.py]"]
  node_chat_api["Chat routes<br/>[chat.py]"]
  node_task_api["Task routes<br/>[tasks.py]"]
  node_event_store[("Event journal<br/>[store.py]")]
  node_dispatcher["Rule dispatcher<br/>[dispatch.py]"]
  node_workers["Background workers<br/>[main.py]"]
end

subgraph group_selection["Program selection"]
  node_selection_agent["Selection assistant<br/>[selection.py]"]
  node_matching["Program matching<br/>[rank.py]"]
  node_program_profile[("Profile and programs<br/>[profiles.py]")]
  node_roadmap["Exam requirements<br/>[requirements.py]"]
end

subgraph group_preparation["Exam preparation"]
  node_diagnostic["Starting assessment<br/>[diagnostic.py]"]
  node_task_engine["Task issuing and grading<br/>[tasks.py]"]
  node_knowledge["Knowledge model<br/>[hlr.py]"]
  node_sets_forecast["Sets and forecast<br/>[assemble.py]"]
end

subgraph group_intelligence["Rules and AI"]
  node_tutor["Tutor and observer<br/>[tutor.py]"]
  node_quack_rules["Change explanations<br/>[quack.py]"]
end

node_learner(("Learner"))
node_llm{{"LLM provider"}}
node_postgres[("PostgreSQL")]
node_knowledge_graph[("Neo4j knowledge graph")]

node_learner -->|"opens"| node_web
node_web -->|"enters selection"| node_choice_ui
node_web -->|"opens preparation"| node_prep_ui
node_choice_ui -->|"calls"| node_api
node_prep_ui -->|"calls"| node_api
node_api -->|"routes requests"| node_chat_api
node_api -->|"routes requests"| node_task_api
node_chat_api -->|"runs chat agent"| node_selection_agent
node_selection_agent -->|"requests language output"| node_llm
node_selection_agent -->|"runs matching"| node_matching
node_matching -->|"reads profile"| node_program_profile
node_learner -->|"saves programs"| node_choice_ui
node_program_profile -->|"supplies saved requirements"| node_roadmap
node_roadmap -->|"exposes exam route"| node_prep_ui
node_prep_ui -->|"starts assessment"| node_diagnostic
node_prep_ui -->|"requests tasks"| node_task_api
node_task_api -->|"issues and records answers"| node_task_engine
node_task_engine -->|"appends task events"| node_event_store
node_task_api -->|"dispatches answer event"| node_dispatcher
node_dispatcher -->|"applies evidence rules"| node_knowledge
node_knowledge -->|"rebuilds learning plan"| node_sets_forecast
node_sets_forecast -->|"returns sets and forecast"| node_prep_ui
node_chat_api -->|"runs prep agent"| node_tutor
node_tutor -->|"requests language output"| node_llm
node_workers -->|"runs chat observer"| node_tutor
node_dispatcher -->|"applies change rules"| node_quack_rules
node_quack_rules -->|"provides change feed"| node_quack_ui
node_program_profile -->|"contributes program changes"| node_quack_rules
node_knowledge -->|"contributes learning changes"| node_quack_rules
node_event_store -->|"persists events"| node_postgres
node_program_profile -->|"stores profile data"| node_postgres
node_knowledge -->|"projects skill state"| node_knowledge_graph
node_llm -->|"returns generated output"| node_tutor

click node_web "https://github.com/steppetech1/quack/blob/main/frontend/src/app/page.tsx"
click node_choice_ui "https://github.com/steppetech1/quack/blob/main/frontend/src/components/choice/ChoiceApp.tsx"
click node_prep_ui "https://github.com/steppetech1/quack/blob/main/frontend/src/components/prep/PrepView.tsx"
click node_quack_ui "https://github.com/steppetech1/quack/blob/main/frontend/src/components/quack/standing.ts"
click node_api "https://github.com/steppetech1/quack/blob/main/backend/app/main.py"
click node_chat_api "https://github.com/steppetech1/quack/blob/main/backend/app/api/chat.py"
click node_task_api "https://github.com/steppetech1/quack/blob/main/backend/app/api/tasks.py"
click node_event_store "https://github.com/steppetech1/quack/blob/main/backend/app/events/store.py"
click node_dispatcher "https://github.com/steppetech1/quack/blob/main/backend/app/events/dispatch.py"
click node_workers "https://github.com/steppetech1/quack/blob/main/backend/app/workers/main.py"
click node_selection_agent "https://github.com/steppetech1/quack/blob/main/backend/app/agents/selection.py"
click node_matching "https://github.com/steppetech1/quack/blob/main/backend/app/matching/rank.py"
click node_program_profile "https://github.com/steppetech1/quack/blob/main/backend/app/db/repo/profiles.py"
click node_roadmap "https://github.com/steppetech1/quack/blob/main/backend/app/roadmap/requirements.py"
click node_diagnostic "https://github.com/steppetech1/quack/blob/main/backend/app/apply/diagnostic.py"
click node_task_engine "https://github.com/steppetech1/quack/blob/main/backend/app/apply/tasks.py"
click node_knowledge "https://github.com/steppetech1/quack/blob/main/backend/app/knowledge/hlr.py"
click node_sets_forecast "https://github.com/steppetech1/quack/blob/main/backend/app/sets/assemble.py"
click node_tutor "https://github.com/steppetech1/quack/blob/main/backend/app/agents/tutor.py"
click node_quack_rules "https://github.com/steppetech1/quack/blob/main/backend/app/apply/quack.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_web,node_choice_ui,node_prep_ui,node_quack_ui toneBlue
class node_api,node_chat_api,node_task_api,node_event_store,node_dispatcher,node_workers,node_postgres,node_knowledge_graph toneAmber
class node_selection_agent,node_matching,node_program_profile,node_roadmap toneMint
class node_diagnostic,node_task_engine,node_knowledge,node_sets_forecast toneRose
class node_tutor,node_quack_rules,node_learner,node_llm toneIndigo
```

## Components

### Learner experience

- [Web app](https://github.com/steppetech1/quack/blob/main/frontend/src/app/page.tsx): `frontend/src/app/page.tsx`
- [Choice interface](https://github.com/steppetech1/quack/blob/main/frontend/src/components/choice/ChoiceApp.tsx): `frontend/src/components/choice/ChoiceApp.tsx`
- [Preparation interface](https://github.com/steppetech1/quack/blob/main/frontend/src/components/prep/PrepView.tsx): `frontend/src/components/prep/PrepView.tsx`
- [Change feed](https://github.com/steppetech1/quack/blob/main/frontend/src/components/quack/standing.ts): `frontend/src/components/quack/standing.ts`

### API and events

- [HTTP API](https://github.com/steppetech1/quack/blob/main/backend/app/main.py): `backend/app/main.py`
- [Chat routes](https://github.com/steppetech1/quack/blob/main/backend/app/api/chat.py): `backend/app/api/chat.py`
- [Task routes](https://github.com/steppetech1/quack/blob/main/backend/app/api/tasks.py): `backend/app/api/tasks.py`
- [Event journal](https://github.com/steppetech1/quack/blob/main/backend/app/events/store.py): `backend/app/events/store.py`
- [Rule dispatcher](https://github.com/steppetech1/quack/blob/main/backend/app/events/dispatch.py): `backend/app/events/dispatch.py`
- [Background workers](https://github.com/steppetech1/quack/blob/main/backend/app/workers/main.py): `backend/app/workers/main.py`

### Program selection

- [Selection assistant](https://github.com/steppetech1/quack/blob/main/backend/app/agents/selection.py): `backend/app/agents/selection.py`
- [Program matching](https://github.com/steppetech1/quack/blob/main/backend/app/matching/rank.py): `backend/app/matching/rank.py`
- [Profile and programs](https://github.com/steppetech1/quack/blob/main/backend/app/db/repo/profiles.py): `backend/app/db/repo/profiles.py`
- [Exam requirements](https://github.com/steppetech1/quack/blob/main/backend/app/roadmap/requirements.py): `backend/app/roadmap/requirements.py`

### Exam preparation

- [Starting assessment](https://github.com/steppetech1/quack/blob/main/backend/app/apply/diagnostic.py): `backend/app/apply/diagnostic.py`
- [Task issuing and grading](https://github.com/steppetech1/quack/blob/main/backend/app/apply/tasks.py): `backend/app/apply/tasks.py`
- [Knowledge model](https://github.com/steppetech1/quack/blob/main/backend/app/knowledge/hlr.py): `backend/app/knowledge/hlr.py`
- [Sets and forecast](https://github.com/steppetech1/quack/blob/main/backend/app/sets/assemble.py): `backend/app/sets/assemble.py`

### Rules and AI

- [Tutor and observer](https://github.com/steppetech1/quack/blob/main/backend/app/agents/tutor.py): `backend/app/agents/tutor.py`
- [Change explanations](https://github.com/steppetech1/quack/blob/main/backend/app/apply/quack.py): `backend/app/apply/quack.py`

### Other components

- **Learner**
- **LLM provider**
- **PostgreSQL**
- **Neo4j knowledge graph**

## Connections

- Learner → Web app: opens
- Web app → Choice interface: enters selection
- Web app → Preparation interface: opens preparation
- Choice interface → HTTP API: calls
- Preparation interface → HTTP API: calls
- HTTP API → Chat routes: routes requests (evidence: `backend/app/main.py`)
- HTTP API → Task routes: routes requests (evidence: `backend/app/main.py`)
- Chat routes → Selection assistant: runs chat agent
- Selection assistant → LLM provider: requests language output
- Selection assistant → Program matching: runs matching
- Program matching → Profile and programs: reads profile
- Learner → Choice interface: saves programs
- Profile and programs → Exam requirements: supplies saved requirements
- Exam requirements → Preparation interface: exposes exam route
- Preparation interface → Starting assessment: starts assessment
- Preparation interface → Task routes: requests tasks
- Task routes → Task issuing and grading: issues and records answers (evidence: `backend/app/api/tasks.py`)
- Task issuing and grading → Event journal: appends task events (evidence: `backend/app/apply/tasks.py`)
- Task routes → Rule dispatcher: dispatches answer event (evidence: `backend/app/api/tasks.py`)
- Rule dispatcher → Knowledge model: applies evidence rules
- Knowledge model → Sets and forecast: rebuilds learning plan
- Sets and forecast → Preparation interface: returns sets and forecast
- Chat routes → Tutor and observer: runs prep agent
- Tutor and observer → LLM provider: requests language output
- Background workers → Tutor and observer: runs chat observer
- Rule dispatcher → Change explanations: applies change rules
- Change explanations → Change feed: provides change feed
- Profile and programs → Change explanations: contributes program changes
- Knowledge model → Change explanations: contributes learning changes
- Event journal → PostgreSQL: persists events
- Profile and programs → PostgreSQL: stores profile data
- Knowledge model → Neo4j knowledge graph: projects skill state
- LLM provider → Tutor and observer: returns generated output
