tutor-service/docs/planning/ARCHITECTURE.md

# 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 typed workflow contracts are defined in
`docs/planning/WORKFLOW_CONTRACTS.md`.

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

The first progression track is the backend developer interview seed list in
`docs/planning/INTERVIEW_TRACKS.md`.

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.