AMTP Docs/Frontend User Stories

Frontend User Stories — Overview & Conventions

This section documents the sharded, INVEST + Gherkin-formatted product backlog for the AMTP web frontend. The application is a pure React SPA; all routing is client-side (React Router), environment variables are baked at build time or fetched via /config, and no Node.js runtime logic exists in the frontend bundle.

Personas

Reading Conventions

Story shape

### Story X.Y — <Imperative title>

**As a** <persona abbrev>
**I want** <capability>
**So that** <user outcome>

**Acceptance criteria**

- **Scenario: <label>**
  - **Given** …
  - **And** …
  - **When** …
  - **Then** …
  - **And** …

Gherkin grammar

• Given — precondition (DB state, session state, or role)
• When — user action or system event
• Then — observable UI change
• And — continuation of preconditions or outcomes
• Scenario: label is mandatory; one label per scenario

Optimistic mutations additionally require a mutation addendum block in each mutating story. Any mutation Gherkin that lacks a prior_state clone in the Given/And block fails PR review.

Source citation format

**Source**
- `@/c:/ZT_AMTP/docs/AMTP_Docs_Website/<page>.html#<anchor>` — purpose

Endpoint map grammar

**Endpoint map**
- `<METHOD> /<path>` — purpose
- `<SSE|WS> /<path>` — streamed payload description
- DB: `<table>.<column>` — state read or written

Cross-Cutting NFRs

These requirements apply to every story across all 15 epics. They are declared here and inherited; epics do not repeat them.

Accessibility

WCAG 2.1 AA — visible focus rings on all interactive elements, full keyboard reachability, semantic landmark regions (<main>, <nav>, <aside>), aria-live regions for all SSE/streaming updates, colour contrast ≥ 4.5:1 for body text, interactive element hit-targets ≥ 44 × 44 CSS px.

Theming

prefers-color-scheme parity with the AMTP docs site. Palette: OKLCH, ZagTrader blue hue 240–241°, accent oklch(63% 0.20 241). Fonts: Chakra Petch (headings) + Hanken Grotesk (body). Callouts use full border: 1px solid + background tint — no accent left-stripes. No hard-coded colour values outside the design-token layer.

Internationalisation & Logical Properties

Copy externalised to i18n resource files. RTL-readiness (Arabic) is mandatory. Physical CSS direction properties are forbidden. CI enforcement is automated and blocks merge with no override path.

Reduced Motion

prefers-reduced-motion: reduce disables stage-timeline animations, skeleton shimmer, and all transition effects; static representations replace them.

Security

• No LLM context or run telemetry stored client-side beyond the OTel browser SDK envelope
• OAuth scope minimisation — request only scopes required for the operation
• CSRF tokens on every state-changing request
• Strict CORS and Content-Security-Policy with no unsafe-inline for scripts
• No third-party analytics scripts on authenticated routes

Privacy — Redaction Filter (dual-mode)

The Redaction Filter (RedactionFilter) operates in two modes:

Every redaction emits a typed breadcrumb to the structured client log and OTel browser SDK envelope. The breadcrumb never carries the value, a prefix, a hash, or any reversible derivative.

Auditor copy/cut/drag interception: On the Artifact Viewer (Epic 5) and Audit Log (Epic 15), the UI intercepts copy, cut, and dragstart events for the Auditor persona, calls event.preventDefault(), runs the selection through the appropriate Redaction Filter mode, and writes only the redacted projection to event.clipboardData/DataTransfer.

Performance Budget

• Time-to-interactive on the run-detail page ≤ 2.5 s p75 on broadband
• SSE first-event latency ≤ 1 s after subscribe

Dev-Prod Parity (Error Provenance)

Every error surface distinguishes between local infra failures (Docker daemon down, missing PEM, Postgres not bootstrapped, Valkey unreachable) and production API failures (GitHub API 5xx, OpenAI provider degradation, OAuth IdP outage). The deciding axis is the VITE_ENV build flag, resolved by the EnvProvenance module. PR reviewers reject error copy that conflates the two.

Traceability — Correlation Chip + Last-Synced Badge

Correlation Chip (CorrelationChip): Every error toast, banner, modal, and empty state renders the Correlation chip showing run_id (when scoped) and request_id from the X-Request-ID response header, copyable to clipboard.

Last-Synced Badge (LastSyncedBadge): Any view rendered from a reconciliation snapshot, prior_state rollback, or SSE Circuit-Breaker stall must display Synced at: <ISO local time> · Snapshot beside the Correlation chip. When the live SSE/WS stream is healthy, the badge reads Live.

Shared Frontend Modules

Failure-Class Distribution

Zero-State Ownership

The cold-start onboarding flow (empty tenant → first project → GitHub App install → first run trigger) is owned by Epic 2 — Project Management. Epics 1 and 3 cross-link to this flow and do not duplicate empty-state acceptance criteria.

Epic Link Tree

Glossary

Core terms are defined at Concepts & Primer.