learning-platform/docs/frontend-spec.md

Frontend spec

A React 19 SPA built with Vite, routed by React Router 7. Entry: src/main.jsx → src/App.jsx. Global state lives in src/store/AppContext.jsx.

---

Routing & access control (src/App.jsx)

Route	Screen	Access
/login	Login.jsx	public
/onboarding	Onboarding.jsx	logged-in, not yet enrolled (enrollment page)
/	Dashboard.jsx	enrolled user
/onboarding-track	OnboardingTrack.jsx	any logged-in user, any enrollment (skipEnrollmentGate)
/learn	Leren.jsx	enrolled user
/test	Testen.jsx	enrolled user
/leaderboard	Leaderboard.jsx	enrolled user
/admin/*	Admin/index.jsx	role === 'admin'

ProtectedRoute:

• redirects to /login if not authenticated;
• redirects to /onboarding if enrollment_status !== 'active' — except admins heading to the admin panel, and routes passing skipEnrollmentGate (the onboarding track), which are exempt;
• enforces requireAdmin for /admin.

/onboarding (enrollment) and /onboarding-track (the 5-day theme intro) are distinct. The track is decoupled from enrollment on purpose so it also works as a refresher for existing staff.

Navigation chrome (top bar + mobile bottom nav) is rendered by ProtectedRoute. ChatLauncher (R42) is mounted globally.

---

Auth & global state (AppContext.jsx)

• Loads team_members on mount; auto-creates an Admin (PIN 0000) if the table is empty.
• PIN login resolves a member and stores the id in sessionStorage.respellion_session.
• state.currentUser holds the member; state.weekNumber is the user's absolute curriculum week, derived from curriculum_started_at via getPersonalWeekNumber (0 until enrolled).
• enrollCurrentUser() stamps curriculum_started_at = now, sets enrollment_status = 'active', and updates state.

---

Onboarding (Onboarding.jsx)

A blocking first-login screen. One CTA — "Start my journey" — calls enrollCurrentUser() and routes to /. Week 1 begins immediately. Users already enrolled are redirected to /. See docs/curriculum-spec.md.

---

Employee screens

• Dashboard — current cycle/week, assigned topic, cycle progress ring, quick links to Learn and Test, mini leaderboard, recent activity. The dismissible "New here?" explainer card also carries the onboarding-track CTA (a progress chip X/5 days + a Start/Continue/Review button linking to /onboarding-track), shown only when the KB has themes to introduce.
• Onboarding Track (/onboarding-track) — a self-paced, breadth-first tour of every theme, grouped into ≤5 day cards (OnboardingTrack.jsx). Opening a theme lazily generates a short overview (what it is / why it matters for daily & weekly work / key points / topics) and offers "Mark as done"; a progress ring + day bar track completion, and a completion banner shows when every theme is done. Available to any logged-in user regardless of enrollment; completion is stored per theme in onboarding_completions. See docs/generation-spec.md §D.
• Learning Station (/learn) — the week's required topic + the rest of the knowledge library; opening a topic shows the micro-learning selector (src/components/micro_learning/). Completing ≥1 micro-learning marks the week done.
• Test (/test) — 5-question quiz with a 5-minute timer, per-question feedback, and a results/review screen. Sets the quiz:active flag to hide R42.
• Leaderboard (/leaderboard) — podium + ranked list + badges (see docs/gamification-spec.md).

Labels show Cycle X · Week Y of 26, where Y/X come from getCurriculumWeek / getCurriculumCycle applied to state.weekNumber.

---

Admin panel (Admin/index.jsx)

Tabbed: Sources (upload + extraction), Content (review/refine generated content), Quizzes, Curriculum (generate/preview/activate a schedule), Graph (D3 knowledge graph + R42 suggestions queue), Team (manage members), Settings (per-tier model overrides, simulation toggle, smoke-test reset).

---

Design system

• CSS variables in src/index.css: colors (--color-bg, --color-paper, --color-teal, --color-accent), radii (--r-sm, --r-lg, --r-org).
• Tailwind v4 utilities map to those variables (bg-teal, text-fg-muted, border-bg-warm, …). Avoid raw hex.
• stylesheet.css (repo root) is the authoritative visual reference — frozen.
• Reuse src/components/ui/ primitives: Card, Button, Tag, Input.
• Framer Motion for entry animations; mobile-first (target 375px).

---

Build (vite.config.js)

• Injects __BUILD_SHA__ / __BUILD_TIME__ (shown by BuildStamp).
• Dev server proxies /api/anthropic to Anthropic and injects ANTHROPIC_API_KEY.
• Source maps on; production build outputs to dist/.