runfoo-org/morethanadiagnosis-hub
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs(openspec): approve and apply 3 infrastructure proposals (Data Model, Authentication, Design System)

Browse source 
Approved proposals:
- Data Model v1: Consolidated schema with PHI/PII classification
- Authentication System: OAuth2/OIDC with RBAC & pseudonym support
- Design System: Unified components with WCAG 2.2 AA+ compliance

Applied to specs:
- openspec/specs/data-model.md (updated with full schema)
- openspec/specs/authentication.md (new)
- openspec/specs/design-system.md (new)
- openspec/specs/architecture.md (added infrastructure references)

All infrastructure proposals now approved and ready for implementation.

🤖 Generated with Claude Code

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
admin 2025-11-18 00:39:01 +00:00
parent 58f8753070
commit 556f74b196
7 changed files with 453 additions and 14 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
openspec/changes/2025-11-17-authentication-system/proposal.md
View file

@ -1,6 +1,6 @@
# Proposal: Authentication & Authorization System # Proposal: Authentication & Authorization System
Status: draft Status: approved
Authors: Security Team, Identity Team Authors: Security Team, Identity Team
Owners: Security Lead, Identity Lead, Architecture Lead Owners: Security Lead, Identity Lead, Architecture Lead
Created: 2025-11-17 Created: 2025-11-17

2
openspec/changes/2025-11-17-data-model-v1/proposal.md
View file

@ -1,6 +1,6 @@
# Proposal: Data Model v1 (Consolidated Schema) # Proposal: Data Model v1 (Consolidated Schema)
Status: draft Status: approved
Authors: Architecture Team, Data Team Authors: Architecture Team, Data Team
Owners: Architecture Lead, Data Lead, Compliance Lead Owners: Architecture Lead, Data Lead, Compliance Lead
Created: 2025-11-17 Created: 2025-11-17

2
openspec/changes/2025-11-17-design-system/proposal.md
View file

@ -1,6 +1,6 @@
# Proposal: Design System & Component Library # Proposal: Design System & Component Library
Status: draft Status: approved
Authors: Design Team, Accessibility Team Authors: Design Team, Accessibility Team
Owners: Design Lead, Accessibility Lead, Mobile Lead, Web Lead Owners: Design Lead, Accessibility Lead, Mobile Lead, Web Lead
Created: 2025-11-17 Created: 2025-11-17

22
openspec/specs/architecture.md
View file

@ -31,7 +31,27 @@ 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. - 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. - Feature flags for risky changes; explicit rollback procedures in each proposal.
Decisions ## 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> - <record cross‑cutting decisions here>
Client platform decisions Client platform decisions

137
openspec/specs/authentication.md Normal file
View file

@ -0,0 +1,137 @@
# Authentication & Authorization System
Status: approved
Owners: Security, Identity, Architecture
Last updated: 2025-11-18
Related proposal: `openspec/changes/2025-11-17-authentication-system/proposal.md`
## Overview
OAuth2/OIDC-based authentication system with role-based access control (RBAC), pseudonym support, session management, and compliance-friendly audit logging.
## User Stories
- As a user, I can sign up with email/password and verify my email
- As a user, I can log in securely and stay logged in across devices
- As a user, I can use a pseudonym in the community without exposing my real name
- As a moderator, I have elevated permissions to manage flagged content
- As an admin, I can view audit logs of authentication events
## Authentication Flow
### Sign Up
- Email/password registration with email verification
- Password hashing: Argon2id (preferred) or bcrypt with high work factor
- Verification email with time-limited token
### Sign In
- OAuth2 authorization code flow with PKCE
- Support for refresh token rotation (30-day expiry)
- Access tokens: short-lived (15 min), JWT signed
- Refresh tokens: opaque, stored server-side, rotated
### Session Management
- Access tokens: 15 min expiry
- Refresh tokens: 30 days, rotated on use
- HttpOnly, Secure, SameSite cookies for web
- Secure storage for mobile apps
## API Endpoints
- `POST /api/v1/auth/signup` — register new user
- `POST /api/v1/auth/verify-email` — verify email with token
- `POST /api/v1/auth/login` — OAuth2 authorization code flow
- `POST /api/v1/auth/token` — exchange code for tokens (PKCE)
- `POST /api/v1/auth/refresh` — rotate refresh token
- `POST /api/v1/auth/logout` — revoke refresh token
- `POST /api/v1/auth/password-reset-request` — send reset email
- `POST /api/v1/auth/password-reset-confirm` — reset password with token
- `POST /api/v1/auth/mfa/enable` — enable TOTP MFA
- `POST /api/v1/auth/mfa/verify` — verify TOTP code
- `GET /api/v1/auth/me` — get current user info
## Roles & Permissions
### Roles
- **member**: read public content, write forum, read own profile
- **moderator**: manage flagged content, moderate forum
- **admin**: admin panel, user management, system audit logs
### RBAC Enforcement
- Middleware-based permission checks on protected endpoints
- Role-based scopes in JWT tokens
- Fine-grained permissions per resource
## Multi-Factor Authentication (MFA)
- TOTP (time-based one-time password) support
- Opt-in (not mandatory initially)
- QR code + manual entry for setup
- Accessible to users with assistive tech
## Account Security
- Password reset: time-limited tokens (15 min)
- Account lockout: after 5 failed login attempts, lock for 30 min
- Brute force protection: rate limit login endpoint (10 attempts per IP per minute)
- Password reset rate limit: 3 per hour per email
- Lockout notification via email
## Pseudonym Support
- User profile includes optional `pseudonym` field
- Forum/community contexts display pseudonym (if set), otherwise display_name
- Moderation/admin views show both pseudonym and real identity
- Audit logging for identity reveals
## Privacy & Compliance
- Email is PII, never logged in plain text
- Passwords never logged
- Audit log: login attempts, password resets, MFA changes (no credentials)
- DSR support: export auth history, delete purges tokens and auth records
- Consistent error messages for signup/login (prevent email enumeration)
## Data Model
- **User**: id, email (PII, unique), password_hash, email_verified, mfa_enabled, mfa_secret (encrypted), locked_until, failed_login_attempts, created_at, updated_at, deleted_at
- **Role**: id, name, permissions
- **UserRole**: id, user_id (FK), role_id (FK)
- **RefreshToken**: id, user_id (FK), token_hash, expires_at, created_at, revoked_at
- **AuthAuditLog**: id, user_id (FK, nullable), event_type, ip_address, user_agent, created_at
## Security Standards
- PKCE required for mobile/SPA
- No custom auth protocol; OAuth2/OIDC standards only
- Rate limiting on all auth endpoints
- Token rotation for refresh tokens
- Session invalidation on logout
- Audit trail for all auth events
## Observability & Telemetry
- Metrics: login success/failure rates, MFA adoption, lockout frequency
- Alerts: spike in failed logins, lockout rate anomalies
- Traces: auth flow latency (signup, login, token exchange)
## Testing
- Unit tests: password hashing, token generation/validation, RBAC
- Integration tests: full auth flows (signup, login, refresh, logout, MFA)
- Security tests: brute force protection, PKCE validation, token expiry
- Accessibility tests: keyboard nav on auth forms, screen reader labels
- Compliance tests: DSR export includes auth history, delete purges tokens
## Rollout Plan
- Deploy to staging; test with pilot users
- Migrate existing users with password reset flow
- Feature flag for MFA (opt-in)
- Monitor login success rates; rollback on anomalies
## Open Questions
- Social login (Google, Apple) support timeline? (Future proposal)
- Passkey/WebAuthn support? (Future proposal)
- Session timeout for inactivity?

89
openspec/specs/data-model.md
View file

@ -1,15 +1,84 @@
# Data Model # Data Model v1 (Consolidated Schema)
Status: draft Status: approved
Owners: Architecture, Data Owners: Architecture, Data, Compliance
Last updated: 2025-11-18
Related proposal: `openspec/changes/2025-11-17-data-model-v1/proposal.md`
Entities (initial) ## Core Entities
- User, Profile, Consent, ForumCategory, ForumThread, ForumPost, BlogPost, Resource, PodcastEpisode, Tribute, Product, Order, MediaAsset.
Notes ### User & Identity
- Mark each field with data class (Public/PII/PHI) and retention policy. - **User**: id, email (PII), password_hash, created_at, updated_at, deleted_at
- Define soft‑delete vs hard‑delete behavior for user‑generated content. - **Profile**: id, user_id (FK), display_name, pseudonym, pronouns, avatar_url, bio, health_journey (PHI), consent_flags, created_at, updated_at
- **Role**: id, name (member, moderator, admin), permissions
- **UserRole**: id, user_id (FK), role_id (FK)
- **Consent**: id, user_id (FK), consent_type, granted, granted_at, revoked_at
Migrations ### Forum Domain
- Version every schema change; ensure reversible steps; seed data for initial categories/resources. - **ForumCategory**: id, name, description, order, created_at
- **ForumThread**: id, category_id (FK), author_id (FK User), title, pinned, locked, created_at, updated_at
- **ForumPost**: id, thread_id (FK), author_id (FK User), parent_post_id (FK), content (may contain PHI), deleted_at, created_at, updated_at
- **ForumReaction**: id, post_id (FK), user_id (FK), emoji_code, created_at
- **ForumReport**: id, post_id (FK), reporter_id (FK User), reason, status, moderator_notes, resolved_at, created_at
### Content Domain
- **BlogPost**: id, author_id (FK User), title, slug, content, published_at, created_at, updated_at
- **Resource**: id, title, slug, content, access_tier (public/members), tags, created_at, updated_at
### Media & Tributes
- **PodcastEpisode**: id, title, description, audio_url, duration, published_at, created_at
- **TributeEntry**: id, author_id (FK User), subject_name, memorial_text (may contain PHI), published, created_at, updated_at
### Commerce
- **MerchProduct**: id, name, description, price, stock_count, created_at, updated_at
- **Order**: id, user_id (FK), total, status, shipping_address (PII), created_at, updated_at
## Data Classification
- **Public**: ForumCategory, PodcastEpisode, Resource (public tier), MerchProduct, BlogPost (published)
- **PII**: User.email, Profile.display_name, Order.shipping_address, Profile.avatar_url
- **PHI**: Profile.health_journey, ForumPost.content (context-dependent), TributeEntry.memorial_text (context-dependent)
## Relationships & Constraints
- User → Profile (1:1, cascade delete)
- User → ForumPost (1:N, soft-delete user → anonymize posts)
- User → ForumThread (1:N)
- ForumCategory → ForumThread (1:N)
- ForumThread → ForumPost (1:N, cascade delete)
- ForumPost → ForumReaction (1:N, cascade delete)
- ForumPost → ForumReport (1:N)
- User → BlogPost (1:N)
- User → TributeEntry (1:N)
- User → Order (1:N)
## Indexing Strategy
- User: email (unique), created_at
- Profile: user_id (unique FK)
- ForumThread: category_id, author_id, created_at
- ForumPost: thread_id, author_id, created_at
- BlogPost: slug (unique), author_id, published_at
- Resource: slug (unique), access_tier, tags (GIN/array)
- Order: user_id, created_at
## Retention & Soft-Delete
- **User**: soft-delete (90-day window); anonymize posts on hard-delete
- **ForumPost**: soft-delete (90-day window); replace author with "[deleted]" on user delete
- **BlogPost, TributeEntry**: indefinite retention unless user requests DSR delete
- **Order**: 7-year retention (tax compliance), then hard-delete
## Migrations
- Versioned migrations (Alembic, Flyway, or similar)
- Idempotent scripts for rollback safety
- Seed data: initial categories, default consents, sample resources
## Security & Compliance
- Encryption at rest: PII/PHI fields encrypted at database or app level
- Access controls: RBAC at API layer; RLS for multi-tenancy if needed
- Audit logging: all PHI/PII mutations logged (excluding content)
- DSR support: export and delete operations mapped to all entities

213
openspec/specs/design-system.md Normal file
View file

@ -0,0 +1,213 @@
# Design System & Component Library
Status: approved
Owners: Design, Accessibility, Mobile, Web
Last updated: 2025-11-18
Related proposal: `openspec/changes/2025-11-17-design-system/proposal.md`
## Overview
Unified design system and component library for Android, iOS, and Web that ensures platform parity, accessibility (WCAG 2.2 AA+), and consistent brand identity.
## Design Tokens
### Colors
**Primary Palette**
- Primary: `#3B82F6` (blue, adjust for brand)
- Secondary: `#8B5CF6` (purple)
- Error: `#EF4444`
- Success: `#10B981`
- Warning: `#F59E0B`
**Background & Text**
- Light background: `#FFFFFF`
- Dark background: `#1F2937`
- Light text: `#111827`
- Dark text: `#F9FAFB`
- Border light: `#D1D5DB`
- Border dark: `#4B5563`
### Typography
**Font Family**
- iOS: SF Pro
- Android: Roboto
- Web: Inter / system-ui
**Font Sizes**
- 12px, 14px, 16px (base), 18px, 20px, 24px, 32px, 48px
**Font Weights**
- 400 (normal), 600 (semibold), 700 (bold)
**Line Heights**
- 1.5 (body), 1.25 (headings)
### Spacing
**Base Unit**: 4px
**Scale**
- 0 (0px), 1 (4px), 2 (8px), 3 (12px), 4 (16px), 5 (20px), 6 (24px), 8 (32px), 10 (40px), 12 (48px), 16 (64px), 20 (80px)
### Border Radius
- sm: 4px
- md: 8px
- lg: 12px
- full: 9999px (pills/circles)
### Shadows
- sm: `0 1px 2px rgba(0,0,0,0.05)`
- md: `0 4px 6px rgba(0,0,0,0.1)`
- lg: `0 10px 15px rgba(0,0,0,0.15)`
## Core Components
### Button
- Variants: primary, secondary, ghost, danger
- Sizes: sm, md, lg
- States: default, hover, active, disabled, loading
- Accessibility: role="button", aria-label if icon-only, keyboard enter/space
- Touch target: min 44x44pt
### Input
- Types: text, email, password, textarea, number
- States: default, focus, error, disabled
- Validation: inline error messages with icon
- Accessibility: visible or aria-label, aria-describedby for errors
### Card
- Variants: elevated (shadow), outlined (border), flat
- Structure: header (optional), body, footer (optional)
- Accessibility: semantic sectioning (article/section)
### Modal / Dialog
- Backdrop overlay with dialog container
- Close button with clear affordance
- Accessibility: role="dialog", aria-modal, focus trap, Esc to close
- Focus management: return focus on close
### Navigation
- **Mobile**: bottom tab bar, app bar (top), drawer (side)
- **Web**: top nav, sidebar (collapsible), breadcrumbs
- Accessibility: role="navigation", aria-current for active route
### Form
- Validation helpers
- Error state styling
- Field grouping
- Accessibility: associated labels, error announcements
### Additional Components
- Checkbox, Radio, Select/Dropdown
- Avatar, Badge, Chip/Tag
- Spinner/Loading, Progress bar
- Tabs, Accordion
- List (virtualized), Link
- Toast/Snackbar
## Accessibility (WCAG 2.2 AA+)
### Core Requirements
- **Keyboard navigation**: tab order, focus indicators, enter/space activation
- **Screen readers**: accessible names, roles, states via ARIA
- **Color contrast**: 4.5:1 for text, 3:1 for UI components
- **Dynamic type**: components scale with user font size
- **Reduced motion**: animations respect `prefers-reduced-motion`
- **Touch targets**: minimum 44x44pt (mobile), 44x44px (web)
### Theme Support
- **Light mode** (default)
- **Dark mode**
- **High contrast mode** (7:1+ contrast ratios)
### Platform-Specific
- **iOS**: VoiceOver support, SF Symbols, native haptics
- **Android**: TalkBack support, Material icons, ripple effects
- **Web**: semantic HTML, focus-visible CSS, responsive
## Platform Adapters
### Mobile (React Native)
- Shared design tokens in JavaScript/JSON
- Platform-specific implementations for iOS/Android
- Expo modules for advanced features
- E2E testing via Detox
### Web (Next.js/React)
- Design tokens in CSS custom properties
- Semantic HTML with ARIA
- Responsive design (mobile-first)
- Storybook for documentation
## Theming System
- Design tokens in single source of truth
- Light/dark/high-contrast variants
- Runtime theme switching
- CSS variables for web, object config for mobile
- Support for future brand customization
## Testing & Quality Assurance
### Automated Tests
- Unit tests: component prop variations, state changes
- Accessibility tests:
- Web: axe, react-native-a11y linters (mobile)
- Automated checks in CI
- Visual regression: screenshot tests for all variants (light/dark/high contrast)
- Cross-platform parity checks
### Manual Testing
- VoiceOver (iOS) / TalkBack (Android) / NVDA/JAWS (web)
- Keyboard-only navigation
- High contrast mode verification
- Touch interaction validation
## Documentation
- **Storybook** for web component showcase
- **Example app** for mobile components
- **Design specifications** for each component
- **Accessibility guidelines** per platform
- **Brand guidelines** and usage patterns
## Release & Versioning
- Semantic versioning (1.0.0)
- Changelog for breaking changes
- Migration guides for component updates
- Quarterly release cycle with patches as needed
## Rollout Plan
**Phase 1 (Core Components)**
- Design tokens + colors, typography, spacing
- Button, Input, Card, Modal
- Basic theming (light/dark)
**Phase 2 (Navigation & Forms)**
- Navigation components
- Form helpers
- List (virtualized)
**Phase 3 (Advanced Components)**
- Tabs, Accordion
- Complex interactions
- Advanced theming (high contrast)
## Integration with Features
- Forum MVP uses design system components
- All new features must use design system
- No custom component creation without approval
- Design review for component additions
## Open Questions
- Final brand colors and logo? (use placeholders initially)
- Icon library choice (SF Symbols, Material, custom SVG)?
- Animation library (Framer Motion for web, Reanimated for mobile)?