morethanadiagnosis-hub/openspec/specs/architecture.md

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.

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