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

# Cynaris MVP implementation handoff

## Deliverable and boundary
Five clickable application prototypes contain 36 core product screens, with eight admin screens and three access screens. The website remains the marketing entry point. This handoff contains real frontend interactions and sample records; it does not contain production authentication, a database, live AI, payment collection, email delivery or real site-wide analytics.

The product prototypes keep business state in memory and reset on a full reload. The simulated access programme and event log use sessionStorage so the admin and demo login journeys can be evaluated in the same browser tab. Do not deploy that mechanism as access security.

## Files
- `dist/apps/{os,analytics,mentor,launch,academy}/index.html`: product entry points.
- `dist/apps/assets/main.js`: shared route, event and rendering controller.
- `dist/apps/assets/{os,analytics,mentor,launch,academy}.js`: product-specific renderers and state transitions.
- `dist/apps/assets/data.js`: fictional seeds, product navigation and sample curricula.
- `dist/apps/assets/ui.js`: reusable forms, dialogs, tables, charts and feedback.
- `dist/apps/assets/mvp.css`: shared visual tokens and responsive application components.
- `dist/apps/assets/access.js`, `auth.js`, `admin.js`: simulated admin/access programme.
- `scripts/build_mvp.py`: application shells, studio and screen inventory generation.
- `screen-manifest.json`: route inventory and purpose of every screen.
- `models.ts`: suggested domain shapes for a production implementation.

## Proposed production architecture
Use a server-rendered public website for search discovery and a separately authenticated application surface. UI components can be ported into the chosen framework; these HTML/CSS prototypes do not mandate one. Put business operations behind a service layer with explicit workspace and identity context.

Suggested boundaries:
1. Identity and tenancy: users, workspaces, memberships, sessions and product entitlements.
2. Product services: OS records, analytics datasets and queries, mentorship plans, startup evidence and learning records.
3. AI gateway: server-side model access, task-specific prompts, provenance, evaluations, usage limits and cancellation.
4. Admin operations: invitations, expiry, entitlements, access requests and audit events.
5. Analytics collection: consent-aware event ingestion and aggregation, separate from security audit logs.

Never expose model keys or connection credentials to browser code. Provider secrets belong in managed server-side secrets. Every database query must be scoped to the workspace and authorised actor, not only hidden by the UI.

## Common API conventions
- Base: `/api/v1`; authenticated requests derive user and workspace from a verified session.
- Lists: `{ items, nextCursor }`, stable sort, validated filters and bounded page sizes.
- Mutations: validated fields; server-generated IDs and timestamps; return canonical saved record.
- Errors: `{ error: { code, message, fieldErrors?, requestId } }`; distinguish validation, forbidden, not found, conflict and retryable service failures.
- Use idempotency keys for invitations, billing mutations, AI jobs and other duplicate-sensitive operations.
- Use version/revision checks for concurrent edits; do not silently overwrite another editor.
- Record auditable access and configuration changes with an actor, target, timestamp and outcome.
- Avoid logging prompts, credentials, private documents or personal data by default.

## UI state contract
Each asynchronous view needs loading, empty, success, validation-error, service-error and forbidden states. A failed save preserves entered fields and offers retry. A successful mutation updates the affected record and summary values, then announces the action. Pagination/filter state belongs in the URL when it is shareable; unsaved drafts need a leave-warning in production.

Native dialog specimens use labelled fields, Escape to close, visible focus and keyboard operation. Production should restore focus to a surviving trigger or sensible fallback after mutations. Charts include textual values. Boards use select-based movement so drag-and-drop is not required.

## Shared design tokens
- Typography: Manrope headings; DM Sans body. Keep production body copy 16px and common controls/labels at least 14px. Use 12px for secondary metadata.
- Base spacing: 4px, with 8/12/16/24/32/48px increments.
- Desktop sidebar: 250px. Collapse to a menu on narrow viewports.
- Cards: 8px radius, 1px neutral border, minimal shadow.
- Product accents: OS #4661C9; Analytics #7254CC; Mentor #A14476; Launch #A3662B; Academy #25745D.
- Wide tables and kanban columns scroll within their region; the page itself must not overflow.
- Do not use colour alone for errors, completion or access state.

## Recommended build order
1. Shared identity, workspace model, server-side authorisation, navigation and component library.
2. OS vertical slice: opportunity → project → task; customer and invoice-draft records.
3. Academy vertical slice: enrol → lesson completion → assessment result.
4. Mentor vertical slice: goal → roadmap → practice → reflection.
5. Launch vertical slice: assumption → experiment → evidence → roadmap.
6. Analytics vertical slice: controlled ingestion → semantic model → query → provenance → saved report.
7. Admin operations, real event aggregation, production SEO configuration and observability.

Order is a practical recommendation, not a schedule or cost estimate. Build one end-to-end slice with its tests before broadening features.

## Common release acceptance
- Correct role/tenant enforcement on every endpoint, including exports and AI context retrieval.
- Validated inputs, safe output rendering, CSRF/session protections and rate limits.
- Accessible keyboard flow, labelled controls, responsive layout and contrast checks.
- Consistent loading/empty/error/success behaviour and recoverable failures.
- AI outputs distinguished from facts, with source context and a review point where needed.
- No sample data, demonstration passwords, simulated metrics or fake connectors in production.
- Consent and retention requirements agreed before collecting real visitor or learner events.