158 lines
4.4 KiB
Markdown
158 lines
4.4 KiB
Markdown
# Tutor Platform Architecture
|
|
|
|
## System Shape
|
|
|
|
The platform is a web service built around workflow-driven tutoring and
|
|
structured learner memory.
|
|
|
|
```text
|
|
Web App
|
|
Student interview practice
|
|
Review plan
|
|
Readiness map
|
|
Challenge ladder
|
|
Material ingestion
|
|
Asset review
|
|
|
|
API Backend
|
|
Go service
|
|
Auth and accounts
|
|
Learning sessions
|
|
Interview questions
|
|
Learner memory
|
|
Ontology and source evidence
|
|
Asset generation jobs
|
|
|
|
Workflow Runtime
|
|
internalized agent-farm-go workflow substrate
|
|
YAML/config-authored workflow definitions
|
|
diagnostic interview
|
|
answer grading
|
|
memory extraction
|
|
ontology analysis
|
|
review-plan generation
|
|
asset prompt generation
|
|
progression and challenge selection
|
|
|
|
LLM Kernel
|
|
third-one
|
|
default model_key: deepseek-v4-flash
|
|
|
|
Memory and Knowledge
|
|
learner memory tables
|
|
ontology graph tables
|
|
source evidence ledger
|
|
generated asset lineage
|
|
```
|
|
|
|
## Workflow Responsibilities
|
|
|
|
Use a Go backend as the product service boundary and internalize
|
|
`agent-farm-go` workflow patterns there. Workflow behavior should still be
|
|
configuration-first: prefer YAML/config composition for agent behavior and only
|
|
add code when a capability cannot be expressed through existing workflow or
|
|
runtime-loadable node patterns.
|
|
|
|
Implementation should follow the engineering rules in
|
|
`docs/planning/ENGINEERING.md`: no manually authored source file over 600 lines,
|
|
SOLID responsibility boundaries, KISS implementation choices, and YAGNI for
|
|
future-only abstractions.
|
|
|
|
Initial workflow set:
|
|
|
|
- `diagnose_job_seeker`
|
|
- `generate_interview_question`
|
|
- `grade_interview_answer`
|
|
- `ask_followup_question`
|
|
- `extract_learning_memory`
|
|
- `build_review_plan`
|
|
- `select_next_challenge`
|
|
- `update_readiness_map`
|
|
- `award_learning_progress`
|
|
- `ingest_learning_material`
|
|
- `build_learning_ontology`
|
|
- `detect_ontology_gaps`
|
|
- `generate_teaching_asset_prompt`
|
|
- `verify_generated_learning_asset`
|
|
|
|
## Gamification Strategy
|
|
|
|
Game-inspired engagement should live on top of learner memory and evidence, not
|
|
beside it. The product should not award progress just for time spent. Progress
|
|
is earned through answer quality, misconception repair, review completion, and
|
|
successful transfer to harder interview scenarios.
|
|
|
|
Core progression surfaces:
|
|
|
|
- readiness map by role and concept
|
|
- challenge ladder per concept
|
|
- short daily interview loops
|
|
- boss questions for integrated concept clusters
|
|
- strong-answer portfolio
|
|
- interview-date campaign plan
|
|
|
|
Progression decisions should read from learner memory and grading evidence.
|
|
They should be exposed as workflow outputs so the service can explain why a
|
|
question, reward, or unlock appeared.
|
|
|
|
## LLM Runtime
|
|
|
|
Use `third-one` as the bounded model execution kernel. The default target is
|
|
`deepseek-v4-flash` through runtime configuration. Product workflows should pass
|
|
explicit task contracts and consume typed outputs rather than relying on freeform
|
|
assistant prose.
|
|
|
|
The Go backend should call the workflow/runtime layer through narrow typed
|
|
interfaces. Product domain code should not shell out ad hoc from handlers or
|
|
parse arbitrary assistant text to mutate learner state.
|
|
|
|
## Memory Strategy
|
|
|
|
Do not make RAG the product center. Retrieval can support evidence lookup, but
|
|
the durable product memory should be structured:
|
|
|
|
- learner profile
|
|
- concept mastery
|
|
- misconceptions
|
|
- practice evidence
|
|
- intervention history
|
|
- spaced review schedule
|
|
- readiness progression
|
|
- challenge history
|
|
|
|
MemPalace can inform temporal, scoped, evidence-preserving memory design.
|
|
Graphify can inform ontology extraction from mixed source materials. The service
|
|
should own its privacy, review, tenant, and deletion semantics directly.
|
|
|
|
## Ontology Strategy
|
|
|
|
Uploaded materials should produce a learning graph:
|
|
|
|
- concepts
|
|
- prerequisites
|
|
- examples
|
|
- interview questions
|
|
- rubrics
|
|
- source evidence
|
|
- missing areas
|
|
- generated candidate assets
|
|
|
|
Every inferred or generated node should carry provenance and review state.
|
|
|
|
## Visual Asset Strategy
|
|
|
|
Use image generation behind a provider abstraction. Product language may call
|
|
the desired provider key `gpt-image-v2`, but implementation must confirm the
|
|
current OpenAI model identifier and API surface before production wiring.
|
|
|
|
Generated asset types:
|
|
|
|
- concept diagrams
|
|
- slide-like lesson slices
|
|
- interview explanation cards
|
|
- worksheet visuals
|
|
- analogy images
|
|
|
|
Each asset should store prompt, source concept, source evidence, model config,
|
|
generation time, review state, and usage context.
|