# OpenSpec Project Conventions and Architectural Guidelines

Status: draft
Owners: Program Lead, Architecture, Compliance
Last updated: 2025-11-17

Purpose
- Define repository‑wide conventions for OpenSpec usage, spec authoring, compliance and accessibility gates, and architectural boundaries.

OpenSpec conventions
- Filenames: use kebab‑case; prefix with domain (e.g., `feature-forum.md`).
- Status labels: `draft`, `in-review`, `approved`, `implemented`, `archived`.
- Each proposal follows the template in `openspec/templates/proposal-template.md` and lives under `openspec/changes/`.
- Accepted specs move to `openspec/specs/` with clear versioning.
- One change = one lifecycle: propose → review → apply → archive.

Slash command conventions
- `/propose <title> [scope=spec|infra|policy] [labels=...] [assignees=...] [model=claude|gpt|copilot]`
- `/review <areas=accessibility,compliance,security,mobile,web,backend>`
- `/apply <spec=<file>> [pr=link]` moves normative text to `openspec/specs/`
- `/archive <reason> [link=PR]` marks closure with traceability
- `/assign @user1 @user2` sets proposal owners

Decision records
- Record important decisions inline in proposals under “Alternatives considered” and “Decision & rationale”.
- For cross‑cutting decisions, add a short entry in `openspec/specs/architecture.md#decisions`.

Architecture (guardrails)
- Modular domain map:
  - Identity & Profiles
  - Community Forum
  - Content (Blog & Resources)
  - Media (Podcast)
  - Tribute/Memorials
  - Commerce (Merch)
  - Compliance, Auditing & Privacy
  - Platform (Mobile/Web Apps) and Design System
  - Integration & APIs

API standards
- OpenAPI-first for HTTP; JSON over HTTPS; WebSocket for realtime.
- OAuth2/OIDC for auth; short‑lived access tokens; rotate refresh tokens.
- Resource versioning via URI (`/v1`) and schema versioning in payloads as needed.
- Pagination, idempotency keys for writes, and explicit rate limits.

Data protection & compliance
- Data classes: `Public`, `PII`, `PHI`. Keep PHI minimized and isolated.
- Encryption: TLS 1.3 in transit, AES‑256 at rest; per‑table/field encryption for PHI/PII where applicable.
- Access controls: role‑based (RBAC) and attribute‑based (ABAC) where necessary; audited access to sensitive data.
- Data retention & deletion: GDPR erase requests and well‑defined retention policies per data class.
- Logging: no PHI/PII in logs; use structured logs with redaction.

Accessibility baseline
- Target WCAG 2.2 AA+; support reduced motion, dynamic type/large fonts, high contrast, screen readers, and keyboard/assistive navigation.
- Mobile: iOS VoiceOver / Android TalkBack parity for all screens.
- Web: semantic landmarks, focus order, ARIA where necessary; test via automated and manual checks per spec.

Observability & quality
- Tracing for backend APIs; structured logs; SLOs for critical user journeys.
- Test pyramid per component: unit, integration, e2e. Accessibility checks included in CI for UI changes.

Release management
- Feature flags for staged rollouts. Rollback plan defined in each proposal.
- Data migrations versioned and reversible; dry‑runs for large imports.

Contribution
- All code contributions must link to an approved OpenSpec change.
- Security review is mandatory for anything touching PHI/PII.