> 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.

# CynarisAcademy — MVP build specification

## Goal and user
Primary users: Learner, educator/cohort manager, content administrator.

Core journey: Catalogue → enrolment → lesson → completion → assessment → learner/cohort 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 |
|---|---|---|---|
| ACADEMY-01 | My learning | `/apps/academy/?screen=overview` | Resume an enrolled pathway and inspect progress. |
| ACADEMY-02 | Course catalogue | `/apps/academy/?screen=catalog` | Explore three sample learning pathways. |
| ACADEMY-03 | Course overview | `/apps/academy/?screen=course` | Inspect the curriculum and enrol. |
| ACADEMY-04 | Learning room | `/apps/academy/?screen=lesson` | Read lessons, navigate modules and record completion. |
| ACADEMY-05 | Knowledge check | `/apps/academy/?screen=assessment` | Answer a three-question assessment and review explanations. |
| ACADEMY-06 | My progress | `/apps/academy/?screen=progress` | Review lessons and assessment outcomes. |
| ACADEMY-07 | Cohort overview | `/apps/academy/?screen=cohort` | Inspect illustrative team progress and preview assignment. |

## Data requirements
- Course, CourseVersion, Lesson, Enrollment, Assessment, AssessmentAttempt, Cohort.
- Pin an enrolment to a content version so edits do not invalidate historic completion.
- Grade assessments on the server using a versioned answer key; keep sensitive answer keys out of production learner payloads.
- Cohort managers can access only their assigned groups; individual learning data is not public.

## Proposed API surface
- `GET /courses; GET /courses/:id`
- `POST /enrollments; GET /my/enrollments`
- `GET /lessons/:id; PUT /lesson-completions/:id`
- `POST /assessment-attempts; GET /assessment-attempts/:id`
- `GET /my/progress; GET /cohorts/:id; POST /cohorts/:id/assignments`

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
- [ ] Enrolment is idempotent and lessons are navigable by keyboard.
- [ ] Marking a lesson complete twice does not increase the count twice.
- [ ] Assessment requires every answer and provides useful explanations.
- [ ] Retakes preserve prior attempts while showing the current result clearly.
- [ ] Learner progress reflects the correct course/version; cohort data is scoped by role.
- [ ] Certificates are not issued until eligibility, identity and content policies are defined.

## 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.