> Original design reference. The current PHP implementation adds MySQL persistence, server-enforced accounts, Groq workflows and PDF export. See [current implementation](IMPLEMENTATION.md) for the release scope.

# CynarisMentor — MVP build specification

## Goal and user
Primary users: Learner preparing for a technical role; optional human mentor in a later phase.

Core journey: Career goal → roadmap → project evidence → practice answer → reflection → progress.

The prototype implements the sample journey in the browser. Production scope includes persistence, validation, identity, authorisation and service integration. Live AI outputs must be explicitly labelled and evaluated.

## Screens
| ID | Screen | Route | Primary behaviour |
|---|---|---|---|
| MENTOR-01 | My workspace | `/apps/mentor/?screen=overview` | Review goal, progress and next focus. |
| MENTOR-02 | My goal | `/apps/mentor/?screen=goals` | Choose role, weekly time and a preparation goal. |
| MENTOR-03 | Learning roadmap | `/apps/mentor/?screen=roadmap` | Mark learning topics complete and review progress. |
| MENTOR-04 | Interview practice | `/apps/mentor/?screen=practice` | Write a response to a role-specific interview question. |
| MENTOR-05 | Practice review | `/apps/mentor/?screen=feedback` | Self-check discussion points and save a reflection. |
| MENTOR-06 | Portfolio | `/apps/mentor/?screen=portfolio` | Create and edit project evidence. |
| MENTOR-07 | Progress | `/apps/mentor/?screen=progress` | Review learning completion and practice history. |

## Data requirements
- CareerGoal, RoadmapItem, PracticeSession, PortfolioProject.
- Changing a goal should version the roadmap rather than discard historical learning records in production.
- Distinguish self-review, human feedback and model-generated feedback in the data and UI.
- Do not convert practice scores into employment eligibility decisions or claim job guarantees.

## Proposed API surface
- `GET/PUT /career-goal`
- `GET/POST /roadmaps; PATCH /roadmap-items/:id`
- `POST /practice-sessions; GET /practice-sessions/:id`
- `POST /practice-sessions/:id/reflections`
- `GET/POST/PATCH /portfolio-projects; GET /learning-progress`

All endpoints inherit the workspace-scoping, pagination, validation, error and audit rules in BUILD-HANDOFF.md. Schemas in models.ts are starting contracts, not complete database migrations.

## Required states
- Loading: stable skeleton or progress indicator with an accessible status message.
- Empty: explain the missing record and offer the first useful action.
- Invalid input: inline field error; preserve all valid inputs.
- Service failure: preserve context and offer a safe retry.
- Forbidden or expired access: explain the restriction without leaking record contents.
- Success: update the visible record and dependent summaries, then announce the change.
- Concurrent edit: surface conflict and let the user review the current version.

## Acceptance criteria
- [ ] Role and time preferences produce an explainable, editable plan.
- [ ] Completing a topic updates the learner’s progress once, without duplicate completion events.
- [ ] Practice answers are preserved if feedback generation fails.
- [ ] Reflection shows the rubric/source and avoids presenting unverified correctness as fact.
- [ ] Portfolio records support edit, validation and later evidence links.
- [ ] Progress measures activity and learning records, not a claim of job readiness.

## AI implementation boundary
AI calls belong on the server behind task-specific contracts. Log model/prompt version and evaluation outcome without retaining sensitive content unnecessarily. Support cancellation, timeout and a non-AI fallback. Human review remains part of consequential decisions. The current prototype uses deterministic sample logic, not a model.

## Deferred scope
Production integrations, billing, real notifications, operational analytics, advanced collaboration and broad automation are not implied by this prototype. Define them after the core workflow is validated with users.