Dmitri d4a5378adf Refactor: migrate frontend to Vite/React, add product backend modules

Frontend:
- Replace Next.js with Vite + React + TypeScript
- Add new component architecture (app-shell, sidebar, dashboard modules)
- Implement product modules: FRAME, safety protocols, walkthrough checkin,
  campus/staff attendance, personality quiz, sign language, classroom timer
- Add shadcn/ui component library with Tailwind CSS
- Remove legacy generated components, stores, and pages

Backend:
- Add product migrations: frame_entries, user_progress, safety_quiz_results,
  walkthrough_checkins, communication_events, personality_quiz_results,
  campus_attendance_config/summaries, staff_attendance_records, content_catalog
- Add corresponding models, services, and routes
- Implement cookie-based auth with refresh token rotation
- Add content catalog seeder with product content
- Migrate to ESLint flat config
- Switch from yarn to npm

Infrastructure:
- Update .gitignore for new tooling
- Add project documentation (CLAUDE.md, docs/)
- Remove deprecated config files and yarn.lock

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

2026-06-09 15:18:23 +02:00

4.2 KiB

Raw Blame History

Auth Integration

Purpose

The product frontend authenticates through backend-owned session cookies.

The backend transport details are documented in backend/docs/cookie-auth.md.

Runtime Configuration

The frontend reads only public browser-safe API configuration from:

VITE_BACKEND_API_URL

Local values live in ignored frontend/.env files; the template value is documented in frontend/.env.example.

Do not add secrets to frontend env files. Vite exposes VITE_* values to the browser bundle.

Auth Flow

AuthContext delegates auth state to useAuthSession from frontend/src/business/auth/hooks.ts.
useAuthSession.signIn calls POST /api/auth/signin/local through frontend/src/shared/api/auth.ts.
The backend sets an HttpOnly auth cookie and returns the current user profile.
useAuthSession restores the session with GET /api/auth/me.
The backend returns the current product profile, including productRole, campus, staffProfile, and permissions.
UI-facing StaffProfile is derived in frontend/src/business/auth/mappers.ts.
useAuthSession.signOut calls POST /api/auth/signout; the backend clears the auth cookie.
SignInModal delegates modal mode, form draft state, validation, and submit workflow to useAuthModalWorkflow.

Refresh Tokens

The refresh flow keeps tokens backend-owned:

Backend sign-in sets short-lived access and long-lived refresh HttpOnly cookies.
Protected API requests use the access cookie only.
POST /api/auth/refresh uses the refresh cookie only, rotates it server-side, sets fresh cookies, and returns the current user profile.
httpClient performs one controlled refresh-and-retry after an access-expiry 401.
If refresh fails because both access and refresh credentials are expired or invalid, the business layer clears the user and redirects to /login.
Non-auth backend failures remain observable errors; no infinite retry and no silent fallback.

The frontend must not read, store, or receive access or refresh token values.

The app exposes /login as the deterministic destination for expired sessions. Sign-in also remains available as a modal for in-app guest prompts.

Rules:

/login must reuse the existing auth business hook and API functions.
Auth-expired redirects must use replace: true.
Safe return paths may be preserved only for same-origin product routes.
Tokens and raw session failure details must never be placed in the URL.
Expired access plus valid refresh must restore the session without redirecting.
Expired access plus expired refresh must redirect to /login without showing a raw error.

Layering

View/provider: frontend/src/contexts/AuthContext.tsx, frontend/src/components/frameworks/SignInModal.tsx, and frontend/src/components/sign-in-modal/
Business logic: frontend/src/business/auth/
API/data access: frontend/src/shared/api/auth.ts
Backend contract types: frontend/src/shared/types/auth.ts

Deferred Product Onboarding

Registration, company creation, campus creation, user creation, staff profile creation, and profile updates are intentionally deferred.

The backend has generated auth signup/profile endpoints, but the customer has not approved the product workflow for creating companies, campuses, users, role assignments, campus assignments, and staff profiles.