docs: bootstrap tutor planning

docs/planning/ARCHITECTURE.md

@@ -0,0 +1,157 @@
+# 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.