# Architecture & APIs

Status: approved
Owners: Architecture

Overview
- Modular, domain‑driven architecture with clear boundaries and open APIs.

Modules
- Identity & Profiles, Forum, Content (Blog/Resources), Media (Podcast), Tribute, Commerce, Compliance, Platform (Design System + Apps), Integration.

Client platforms
- Mobile: Android/iOS (proposed: React Native/Expo or Flutter — to be decided via proposal)
- Web: Next.js/SSR or Flutter Web — parity is mandatory and defined per feature spec

Backend
- Proposed: API service with OpenAPI, Postgres primary store, object storage for media, search index for forum/content, queue for async tasks.

API standards
- REST+JSON with OpenAPI; WebSocket for realtime forum/presence; OAuth2/OIDC; rate limits; pagination; idempotency keys.

Data boundaries
- Strict separation of PHI/PII domains; audit and consent services.

Quality gates & SLOs
- SLOs: p95 API latency ≤ 300ms for read endpoints; p95 ≤ 600ms for writes; 99.9% uptime for auth and read APIs, 99.5% for writes.
- CI: OpenAPI validation, breaking‑change detection, security linters, dependency vulnerability checks.
- No PHI/PII in logs; redaction in place before merging.

Implementation notes
- Platform decision path: compare RN/Expo vs Flutter (mobile) and Next.js vs Flutter Web (web) in focused proposals; both must meet a11y and parity requirements.
- Feature flags for risky changes; explicit rollback procedures in each proposal.

## Supporting Infrastructure Specs

### Data Model
- Consolidated schema with all entities across features
- Field-level data classification (Public/PII/PHI)
- Relationships, indexing, retention policies
- See: `openspec/specs/data-model.md`

### Authentication & Authorization
- OAuth2/OIDC with RBAC and pseudonym support
- Session management, MFA, account security
- Compliance-friendly audit logging
- See: `openspec/specs/authentication.md`

### Design System
- Unified component library across Android/iOS/Web
- Design tokens (colors, typography, spacing)
- WCAG 2.2 AA+ accessibility built-in
- See: `openspec/specs/design-system.md`

## Decisions
- <record cross‑cutting decisions here>

Client platform decisions
- Mobile: React Native + Expo (TypeScript).
  Rationale: strong a11y ecosystem, mature tooling, and DX.
  Notes: Expo modules; E2E via Detox; push via Expo/FCM/APNs.
- Web: Next.js (SSR).
  Rationale: semantic HTML, SEO, CWV, and ecosystem maturity.
  Notes: App Router, server actions; sitemap, RSS for blog/resources.

Decision log
- 2025-11-17 — Mobile stack: React Native + Expo.
- 2025-11-17 — Web stack: Next.js (SSR).