How steppetech1/quack works
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: PrepView.tsx Preparation interface · profiles.py Profile and programs · hlr.py Knowledge model · main.py HTTP API
Components 24
Learner experience
- Web app
frontend/src/app/page.tsx - Choice interface
frontend/src/components/choice/ChoiceApp.tsx - Preparation interface
frontend/src/components/prep/PrepView.tsx - Change feed
frontend/src/components/quack/standing.ts
API and events
- HTTP API
backend/app/main.py - Chat routes
backend/app/api/chat.py - Task routes
backend/app/api/tasks.py - Event journal
backend/app/events/store.py - Rule dispatcher
backend/app/events/dispatch.py - Background workers
backend/app/workers/main.py
Program selection
- Selection assistant
backend/app/agents/selection.py - Program matching
backend/app/matching/rank.py - Profile and programs
backend/app/db/repo/profiles.py - Exam requirements
backend/app/roadmap/requirements.py
Exam preparation
- Starting assessment
backend/app/apply/diagnostic.py - Task issuing and grading
backend/app/apply/tasks.py - Knowledge model
backend/app/knowledge/hlr.py - Sets and forecast
backend/app/sets/assemble.py
Rules and AI
- Tutor and observer
backend/app/agents/tutor.py - Change explanations
backend/app/apply/quack.py
Other components
- Learner
- LLM provider
- PostgreSQL
- Neo4j knowledge graph
Connections 33
- 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
backend/app/main.py - HTTP API → Task routes: routes requests
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
backend/app/api/tasks.py - Task issuing and grading → Event journal: appends task events
backend/app/apply/tasks.py - Task routes → Rule dispatcher: dispatches answer event
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