Tutor Platform Architecture

System Shape

The platform is a web service built around workflow-driven tutoring and structured learner memory.

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.

4.4 KiB Raw Blame History