69 lines
3.2 KiB
Markdown
69 lines
3.2 KiB
Markdown
# 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.
|
||
|