tutor-service/docs/planning/PRD.md

# Tutor Platform PRD

## Product Thesis

Build a web service that helps software job seekers prepare for technical
interviews through adaptive tutoring, interview-question practice, and a
student-specific learning memory. The first market is developers preparing for
employment or career transition. The platform should later expand to general
students by reusing the same curriculum, ontology, assessment, and tutoring
workflow foundations.

This is not a classic RAG chatbot. Source materials are ingested as evidence,
analyzed into a learning ontology, checked for missing or weak areas, verified,
and then transformed into structured learning material, practice questions, and
teaching aids.

## Target Users

### Primary: software job seekers

- Bootcamp graduates preparing for interviews.
- Junior developers preparing for first jobs.
- Developers changing stacks.
- Experienced developers preparing for system design, backend, frontend, data,
  AI, DevOps, or language-specific interviews.

### Secondary: general students, later

- Students who need adaptive study plans.
- Teachers or parents who need progress summaries.
- Institutions that want a private learning memory and curriculum engine.

## Problem

Job seekers have abundant content but weak feedback loops:

- They do not know which concepts they truly understand.
- They memorize interview answers without building transferable understanding.
- Existing tools give generic questions, not diagnosis-based practice.
- Study materials are fragmented across notes, PDFs, slides, videos, blogs, and
  repositories.
- Progress is hard to measure across concepts, mistakes, and repeated sessions.

## Product Goals

- Provide interview-first tutoring for software job seekers.
- Build a durable learner model from every practice answer and tutor session.
- Convert uploaded materials into a concept ontology and verified study assets.
- Detect missing, weak, outdated, or unverified parts of a learning corpus.
- Generate practice questions, explanations, review plans, and visual teaching
  aids from the verified ontology.
- Use game-inspired progress loops to make learning feel rewarding, repeatable,
  and visibly connected to interview readiness.
- Keep the architecture reusable for future general-student learning flows.

## Technology Direction

- Backend: Go.
- Workflow substrate: internalize `agent-farm-go` patterns and execution
  contracts into the backend boundary instead of treating workflow execution as
  a loose external script.
- LLM kernel: `third-one`, defaulting to `deepseek-v4-flash` through runtime
  configuration.
- Frontend: web-first. The exact frontend stack remains open until the first UI
  implementation slice, but it should stay lightweight and product-focused.

## Non-Goals for MVP

- Full school LMS replacement.
- Marketplace for courses.
- Automatic certification or hiring decisions.
- Broad multi-subject K-12 coverage.
- Unverified autonomous content publishing.

## MVP Scope

The first MVP should prove one loop:

1. User chooses a target role and stack.
2. Platform runs a diagnostic technical interview.
3. Tutor asks follow-up questions based on weak answers.
4. System extracts concept mastery, misconceptions, and evidence.
5. User receives a focused review plan.
6. User repeats practice with generated interview questions.
7. User sees visible readiness progress, next unlocks, and a recommended next
   challenge.

First track:

- Backend developer interview preparation.
- Topics: HTTP and web fundamentals, REST/API design, databases and indexes,
  transactions and consistency, caching, concurrency/async work, testing and
  reliability, and system design basics.
- Canonical seed list: `docs/planning/INTERVIEW_TRACKS.md`.

## Core User Flows

### Diagnostic interview

The user selects role, stack, target company type, and interview date. The
system asks a short series of adaptive questions, grades answers, identifies
weak concepts, and creates an initial study map.

### Practice session

The tutor asks one interview question at a time, requests the user's answer,
grades it against a rubric, asks follow-ups, and records learning evidence.

### Review plan

After each session, the system creates a concise plan:

- concepts to review
- mistakes to fix
- next practice questions
- suggested study order
- estimated readiness

### Gamified learning routine

The user follows a short loop:

1. choose or accept today's target
2. answer one interview question
3. receive rubric feedback
4. handle one follow-up or correction
5. see memory and readiness progress
6. unlock the next challenge or review card

The loop should feel like a game challenge ladder, but its rewards must be tied
to real learning evidence. The product should favor mastery, autonomy, and
readiness over empty points or exploitative streak pressure.

### Material ingestion

The user or operator uploads PDFs, notes, slides, docs, links, code snippets, or
existing interview-question sets. The system analyzes them into a concept graph,
detects missing prerequisites, flags weak evidence, and proposes generated
study assets.

### Teaching-aid generation

For concepts that need visual explanation, the system generates images,
slide-like lesson slices, diagrams, and worksheet-style teaching aids through
the configured image generation provider.

## Functional Requirements

### Interview question engine

- The system SHALL generate role-specific technical interview questions.
- The system SHALL support difficulty levels and follow-up questions.
- The system SHALL grade answers with rubric-backed evidence.
- The system SHALL separate factual correctness, depth, communication clarity,
  and production judgment.
- The system SHALL keep original user answers as evidence for later review.

### Learner memory

- The system SHALL maintain a per-user learner profile.
- The system SHALL track concept mastery over time.
- The system SHALL track recurring misconceptions and weak reasoning patterns.
- The system SHALL store evidence for every memory update.
- The system SHALL distinguish durable memory from temporary session context.

### Ontology builder

- The system SHALL ingest source materials into a learning ontology.
- The system SHALL represent concepts, prerequisites, examples, questions,
  rubrics, and source evidence as separate entities.
- The system SHALL detect missing prerequisite concepts.
- The system SHALL flag generated or inferred content that lacks source support.
- The system SHALL support human review before promoted learning assets become
  canonical.

### Tutor workflows

- The system SHALL run tutoring behavior through configurable LLM workflows.
- The system SHALL use `agent-farm-go` as the workflow orchestration substrate.
- The backend SHALL be implemented in Go so the service can internalize
  `agent-farm-go` workflow patterns and contracts directly.
- The system SHALL use `third-one` as the LLM execution kernel.
- The default LLM runtime SHALL target `deepseek-v4-flash` unless changed by
  configuration.
- Workflow outputs SHALL prefer typed JSON contracts for grading, memory
  extraction, ontology updates, and review-plan generation.
- Initial workflow contract plan SHALL follow
  `docs/planning/WORKFLOW_CONTRACTS.md`.

### Visual teaching assets

- The system SHALL generate educational visual assets for selected concepts.
- The system SHALL support slide-like lesson slices, diagrams, worksheets, and
  interview explanation cards.
- Image generation SHALL be behind a provider/model configuration key. The
  initial product intent is `gpt-image-v2`; implementation must verify the
  actual OpenAI model identifier before wiring production calls.
- Generated assets SHALL keep source links, prompt lineage, and review state.

### Engagement and progression

- The system SHALL expose a role-specific readiness map.
- The system SHALL organize concepts into challenge ladders from definition to
  pressure-tested interview answers.
- The system SHALL provide short daily or session-based learning loops.
- The system SHALL use adaptive difficulty to keep questions near the user's
  current ability.
- The system SHALL provide meaningful rewards such as concept readiness,
  strong-answer portfolio entries, boss questions, review cards, or visual
  completion assets.
- The system SHALL avoid gambling-like random rewards, shame-based leaderboards,
  and punitive streak loss.

## Memory Model

The memory layer should store structured learning state, not just retrieved
text chunks.

Core memory objects:

- `LearnerProfile`: target role, stack, timeline, preferences.
- `ConceptMastery`: concept-level state such as unknown, fragile, improving, or
  mastered.
- `Misconception`: recurring wrong model or reasoning pattern.
- `Evidence`: original answer, quiz result, source passage, or tutor note that
  supports a memory update.
- `Intervention`: explanation, hint, visual, analogy, or practice type that was
  tried and whether it helped.
- `ReviewSchedule`: when and why a concept should be revisited.

MemPalace is useful as a reference for scoped, temporal, evidence-preserving
memory. Graphify is useful as a reference for building queryable knowledge
graphs from mixed materials. The product memory should still be implemented as
an application-owned data model because learner privacy, tenant boundaries,
review states, and deletion policies are product requirements.

## Success Metrics

- A user can complete a diagnostic interview in under 15 minutes.
- The system produces concept weaknesses that match human reviewer judgment.
- Generated follow-up questions target the user's actual weak points.
- The user can see progress across repeated practice sessions.
- Users complete repeated 5-10 minute learning loops without needing manual
  planning.
- Readiness progress corresponds to actual graded answer evidence.
- Every durable memory update has inspectable evidence.
- Uploaded material produces a useful concept graph and a list of missing or
  weak areas.
- Generated learning assets are reviewable before becoming canonical.

## Risks

- The tutor may overstate correctness or readiness.
- Generated ontology edges may look plausible but lack evidence.
- Job seekers may want company-specific interview prep before the core learning
  loop is reliable.
- Image generation model names and API capabilities may change.
- Learner data can become sensitive, especially when expanding to minors or
  school contexts.

## Open Questions

- Which stack should be the first interview track: backend Go, backend
  Java/Spring, frontend React, or full-stack TypeScript?
- Should users upload their resume first, or should the first session start
  with role/stack selection only?
- How much human review is required before generated ontology content becomes
  canonical?
- Should teacher/operator review exist in MVP, or only after the job-seeker loop
  is proven?
- Which progression surface should ship first: readiness map, challenge ladder,
  strong-answer portfolio, or interview-date campaign?