[jacksonsr451]

Summary

Closes #13

Implements the EventFlow Webapp foundation using React, TypeScript, and Vite, delivering a responsive application shell, accessible navigation, shared design system, and integration with the existing Work Management API and FastAPI authentication BFF.

The implementation establishes the frontend architecture for managing Consultations, Triage, Proposals, WorkItems, Kanban Boards, Projects, Workspaces, and Settings.

It also includes typed API integration, OpenAPI-generated contracts, authentication and session handling, accessibility improvements, automated testing, and CI validation.

Real Keycloak, FastAPI BFF, and PostgreSQL integration were successfully validated.

Changes

1. Webapp Architecture

• Implemented the React and TypeScript Webapp.
• Configured Vite for development and production builds.
• Established application routing and layout infrastructure.
• Integrated the application with the existing monorepo.
• Preserved architectural boundaries defined by ADR-007 and ADR-009.
• Kept domain business logic within the backend.

2. Application Shell and Navigation

Implemented a responsive application shell with navigation for:

• Dashboard.
• Consultations.
• Triage.
• Proposals.
• WorkItems.
• Kanban Boards.
• Projects.
• Workspaces.
• Settings.

Additional capabilities include:

• Desktop and mobile navigation.
• Active route indicators.
• Workspace and Project context.
• Protected routes.
• Browser navigation support.
• Accessible navigation controls.
• Keyboard focus management.

3. Shared Design System

Implemented reusable UI components in packages/ui.

The design system provides:

• Shared design tokens.
• Consistent typography and spacing.
• Reusable interface components.
• Light, dark, and system themes.
• Responsive layouts.
• Accessible focus states.
• Consistent loading, empty, and error states.
• Permission-denied and not-found states.

The shared component architecture supports future client reuse without introducing unnecessary framework coupling.

4. Work Management Interfaces

Implemented the application foundations for:

Dashboard

• Workspace overview and navigation.
• Consistent data-loading and error handling.

Consultations

• Consultation inbox interface.
• Navigation to Consultation details.
• Loading, empty, and error states.

Triage

• Triage workspace and navigation.
• Integration-ready presentation of existing triage data.

Proposals

• Proposal navigation and interface foundation.
• Support for existing Proposal lifecycle representations.

WorkItems

• WorkItem navigation and interface foundation.
• Consistent status and context presentation.

Kanban Boards

• Board navigation and layout foundation.
• Responsive board presentation.

Projects, Workspaces, and Settings

• Navigation and contextual interface foundations.
• Workspace and Project awareness.

Advanced business workflows remain governed by their respective backend contracts and follow-up issues.

5. Authentication and Session Security

Integrated the Webapp with the existing FastAPI BFF and Keycloak architecture.

Supported behavior includes:

• OIDC Authorization Code Flow with PKCE.
• Backend-managed authentication sessions.
• HttpOnly session cookies.
• Session restoration after browser reload.
• Protected route handling.
• Centralized handling of HTTP 401 responses.
• Login and logout flows.
• CSRF protection for unsafe requests.
• Origin validation.
• Safe return-path validation.

OAuth access and refresh tokens are not stored in browser localStorage or sessionStorage.

6. Real Authentication Integration

Validated against running Keycloak and FastAPI BFF services.

Confirmed:

• Keycloak discovery endpoint returned HTTP 200.
• BFF /health/live returned HTTP 200.
• BFF /health/ready returned HTTP 200.
• Unauthenticated /v1/auth/session returned HTTP 401 with application/problem+json.
• OIDC login endpoint returned HTTP 302 with the expected redirect and cookie behavior.
• Real OIDC login succeeded.
• Session cookie used HttpOnly and SameSite=Lax.
• Authenticated session persisted after page reload.
• Real logout succeeded.
• CSRF and Origin protections were covered by authentication/security tests.
• Session expiration and revocation behavior were covered by authentication tests.

7. Typed API Client and Contracts

Implemented or extended shared API infrastructure.

Capabilities include:

• Typed API requests and responses.
• OpenAPI-generated TypeScript definitions.
• Workspace and Project context handling.
• Structured RFC 9457 Problem Details errors.
• Authentication-aware request handling.
• CSRF integration.
• Support for existing API concurrency contracts.

Added a CI check to prevent generated TypeScript contracts from becoming inconsistent with the OpenAPI specification.

The CI executes:

pnpm codegen
git diff --exit-code -- packages/domain/src/work-management.schema.d.ts

8. PostgreSQL and Backend Validation

Validated the existing Work Management backend using the project's Poetry environment.

• Repaired the local backend dependency environment.
• Started and validated PostgreSQL.
• Started and validated Keycloak.
• Applied database migrations to the current head.
• Executed the Work Management test suite.
• Executed root contract and security tests.

The implementation also includes a compatibility correction to migration 0008, ensuring the required composite constraint is created idempotently for applicable database states.

9. Accessibility and Responsiveness

Implemented accessibility foundations including:

• Semantic landmarks.
• Accessible navigation.
• Keyboard interaction.
• Visible focus states.
• Accessible status and error presentation.
• Focus management.
• Screen-reader announcements.
• Responsive desktop and mobile layouts.

Automated accessibility checks passed.

Full manual WCAG conformance verification remains outside the completed validation evidence.

10. Testing

Backend and Contracts

Suite	Result
Work Management	225 passed
Root contract/security	114 passed
Contract validation	Passed
PostgreSQL integration	Passed
Database migrations	Passed

One Starlette/httpx deprecation warning remains.

Frontend

Suite	Result
API client	9 passed
UI/accessibility	7 passed
Webapp Vitest/RTL/MSW	2 passed
Playwright deterministic E2E	3 passed
Playwright real BFF/Keycloak E2E	1 passed
Production build	Passed
Lint	Passed
Typecheck	Passed
OpenAPI code generation	Passed
Generated contract consistency	Passed
Pre-commit hooks	Passed

The targeted frontend suites are reported separately.

11. Continuous Integration

Updated .github/workflows/ci.yml to validate:

• Frozen-lockfile dependency installation.
• OpenAPI code generation.
• Generated contract consistency.
• Frontend lint.
• TypeScript typecheck.
• Unit and component tests.
• Production build.
• Deterministic Playwright E2E tests.

Existing backend contract, persistence, and authentication checks were preserved.

Real BFF/Keycloak E2E tests are available through the opt-in test:e2e:real workflow rather than being required by ordinary pull-request checks.

Acceptance Criteria

• React Webapp implemented.
• Responsive application shell implemented.
• Dashboard navigation implemented.
• Consultation inbox implemented.
• Triage interface foundation implemented.
• Proposals interface foundation implemented.
• WorkItems interface foundation implemented.
• Kanban Boards interface foundation implemented.
• Projects and Workspaces navigation implemented.
• Settings interface implemented.
• Shared design system implemented.
• Light/dark/system themes implemented.
• Loading, empty, and error states implemented.
• Permission-denied and not-found states implemented.
• BFF authentication integrated.
• Real Keycloak login validated.
• HttpOnly session handling validated.
• CSRF protections validated.
• Logout validated.
• Typed API client integrated.
• OpenAPI contracts synchronized.
• Accessibility tests passed.
• Frontend automated tests passed.
• Deterministic E2E tests passed.
• Real authentication E2E passed.
• Backend tests passed.
• PostgreSQL integration tests passed.
• Production build passed.
• CI configuration updated.
• Documentation updated.
• Full real-browser Workspace business workflow validated.
• Complete manual accessibility audit performed.
• Remote CI verified.
• Pull Request reviewed and approved.

Known Limitations

Real Workspace Business Workflow

The local Keycloak test user does not have an associated Workspace membership.

Consequently, real-browser validation covered authentication, session persistence, API connectivity, and logout, but did not execute a complete authorized Workspace mutation or business-data navigation flow.

Workspace authorization and isolation are covered by backend tests.

Real Integration CI

Real Keycloak/BFF E2E tests require a configured integration environment and are intentionally opt-in.

Deterministic browser tests remain part of standard PR validation.

Responsive and Accessibility Verification

Responsive behavior and automated accessibility tests passed.

A complete manual review across all target breakpoints (320px, 375px, 768px, 1024px, and 1440px) and a dedicated WCAG audit remain recommended.

Existing Dependency Warning

The backend test suite reports one Starlette/httpx deprecation warning.

No test failures were reported.

Review Focus

Reviewers should pay particular attention to:

1. Webapp architecture and monorepo boundaries.
2. Shared UI component design.
3. Responsive navigation and keyboard accessibility.
4. BFF authentication and session lifecycle.
5. CSRF and Origin handling.
6. Workspace/Project context isolation.
7. Typed API-client behavior.
8. OpenAPI code generation consistency.
9. PostgreSQL migration 0008 compatibility correction.
10. CI coverage and real integration test limitations.

Commit

d2ae79673327388cc680a4194f0cd1bc208dca4a

feat(web): implement webapp shell navigation and design system (#13)

Final Status

READY FOR REVIEW — WITH DOCUMENTED RESERVATIONS

The frontend implementation, backend tests, PostgreSQL integration, real Keycloak authentication, and local quality checks passed.

The remaining limitations concern complete real-browser Workspace business workflow coverage, manual accessibility verification, and pending remote CI/review.