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

# CynarisAnalytics — MVP build specification

## Goal and user
Primary users: Business viewer, analyst, data administrator.

Core journey: Source → schema/quality review → question → checked answer → dashboard → report.

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 |
|---|---|---|---|
| ANALYTICS-01 | Overview | `/apps/analytics/?screen=overview` | Inspect metrics and start a supported data question. |
| ANALYTICS-02 | Data sources | `/apps/analytics/?screen=sources` | Load labelled sample sources and review planned connector flows. |
| ANALYTICS-03 | Dataset inspector | `/apps/analytics/?screen=dataset` | Inspect the 18-row revenue dataset and its structure. |
| ANALYTICS-04 | Ask your data | `/apps/analytics/?screen=explorer` | Ask supported sample questions, filter regions and save an insight. |
| ANALYTICS-05 | Dashboards | `/apps/analytics/?screen=dashboards` | Choose widgets and create a report snapshot. |
| ANALYTICS-06 | Reports | `/apps/analytics/?screen=reports` | Review saved insights and report snapshots. |
| ANALYTICS-07 | Workspace settings | `/apps/analytics/?screen=settings` | Edit workspace preferences and review access design. |

## Data requirements
- DataSource, Dataset, semantic metric definitions, AnalysisQuery, Dashboard, ReportSnapshot.
- Every answer records dataset version, applied filters, units, freshness and source provenance.
- Translate free text only within an authorised semantic scope; validate generated queries before execution.
- Apply row/column access policies in query execution and model context; never rely on the prompt for authorisation.

## Proposed API surface
- `GET/POST /data-sources; POST /data-sources/:id/refresh`
- `GET /datasets/:id/schema; GET /datasets/:id/preview`
- `POST /queries; GET /queries/:id; POST /queries/:id/cancel`
- `GET/POST /insights; GET/POST/PATCH /dashboards`
- `POST /report-snapshots; GET /report-snapshots/:id`

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
- [ ] Regional and period filters yield consistent totals from the same dataset version.
- [ ] Unsupported questions produce a helpful clarification instead of fabricated answers.
- [ ] A saved insight retains its question, filters, provenance and result snapshot.
- [ ] A failed query can be retried without losing its question or creating duplicate jobs.
- [ ] Connector credentials stay on the server; preview pages do not expose private tables.
- [ ] Reports distinguish observed changes from inferred causes and label data freshness.

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