ADR: Documentation Strategy & Repository Restructure
Status: ACCEPTED Date: 2026-01-23 Context: The repository's documentation is currently dispersed, making it difficult to maintain a clear "Source of Truth" vs. "Ephemeral Planning". The current
architecture/directory mixes long-term standards with short-term specs.
1. The Decision
We will restructure the repository to separate Persistent Knowledge (The Library) from Ephemeral Planning (The Workbench), but co-locate them within a single ordered lifecycle in documentation/.
2. The Grand Library (documentation/)
This directory is the "Evergreen" reference. If it is here, it is true. The structure reflects the System Life Cycle.
| Directory | Content Type | Examples |
|---|---|---|
01_architecture/ |
The Constitution | Blueprints, Core Books (Moved from architecture/GOLDEN) |
02_standards/ |
The Rules | Coding Style, Compliance, Governance |
03_technology/ |
The Tech | ADRs, Decision Logs, Stack Choices |
04_development/ |
The Workbench | "Right Now" planning (See detail below) |
05_operations/ |
The Runbooks | DevOps Guides, Deployments, Sentry Configs |
06_product/ |
The Value | User Manuals, Persona Definitions, Feature Specs |
07_data/ |
The State | Schemas, Data Dictionaries, Seed Strategies |
08_security/ |
The Shield | Audits, RBAC Models, Incident Reports |
Detail: 01_architecture (The Constitution)
High-level system design and immutable core principles.
| Sub-Directory | Content / Taxonomy | Description |
|---|---|---|
blueprints/ |
System Context | C4 Diagrams, Context Maps, Boundary Definitions |
manifesto/ |
Core Values | Project Vision, Mission Statements, "The Why" |
patterns/ |
Reference Architectures | Approved patterns (e.g., "Event Driven", "MVI") |
Detail: 02_standards (The Rules)
The laws that govern code quality and contribution.
| Sub-Directory | Content / Taxonomy | Description |
|---|---|---|
coding/ |
Style Guides | TypeScript Rules, Linters, CSS Conventions |
process/ |
Workflow | Git Flow, PR Templates, Review Checklists |
compliance/ |
Legal & Audit | License headers, Accessibility (a11y) standards |
ai_governance/ |
Agent Rules | .cursorrules, Prompts, Human/AI Collaboration Protocols |
Detail: 03_technology (The Tech)
Specific technology choices and decisions.
| Sub-Directory | Content / Taxonomy | Description |
|---|---|---|
decisions/ |
ADRs | Architectural Decision Records (Immutable) |
stack/ |
Tooling | Why Next.js? Why Upstash? Why Doppler? |
libraries/ |
Dependencies | Third-party package audits and approvals |
Detail: 04_development (The Workbench)
This directory is for "Right Now". It is time-bound and disposable.
| Sub-Directory | Content / Taxonomy | Description |
|---|---|---|
planning/ |
The Calendar | Sprints, Roadmaps, Quarterly Goals |
proposals/ |
The Drafts | RFCs, Rough Sketches, Pre-ADR thinking |
scratchpad/ |
The Noise | Temporary notes, pastebins (Gitignored patterns) |
Detail: 05_operations (The Runbooks)
How to build, run, and monitor the system.
| Sub-Directory | Content / Taxonomy | Description |
|---|---|---|
deployments/ |
CI/CD | Vercel pipelines, GitHub Actions, Release Engineering |
monitoring/ |
Observability | Sentry Dashboards, Logging Strategies, Health Checks |
manuals/ |
SOPs | "How to Rotate Secrets", "How to Restore Backup" |
onboarding/ |
Getting Started | Developer Setup, "Day 1" Guide, Environment Config |
Detail: 06_product (The Value)
What we are building and who it is for.
| Sub-Directory | Content / Taxonomy | Description |
|---|---|---|
personas/ |
Users | User Profiles, Customer Journeys, Empathy Maps |
features/ |
Capabilities | Feature Specifications, Acceptance Criteria |
manuals/ |
Help Docs | User-facing documentation (KB articles) |
registry/ |
External Assets | Links to Figma, Linear, Vercel Dashboards, 3rd Party Tools |
Detail: 07_data (The State)
Information architecture and storage.
| Sub-Directory | Content / Taxonomy | Description |
|---|---|---|
dictionary/ |
Definitions | Business Glossary, Domain Language (Ubiquitous Language) |
schemas/ |
Models | Prisma Schema docs, JSON Validation Rules |
migration/ |
Lifecycle | Data Migration Plans, Seeding Strategies |
Detail: 08_security (The Shield)
Protection, Auditing, and Access Control.
| Sub-Directory | Content / Taxonomy | Description |
|---|---|---|
policies/ |
Governance | RBAC Matrices, Access Policies, Data Classification |
audits/ |
Reports | Pen Test Reports, Automated Scans, Incident Post-Mortems |
threats/ |
Modeling | Attack Surface Analysis, Mitigation Strategies |
3. Migration Map ("As-Is" -> "To-Be")
| Current Location | New Destination | Notes |
|---|---|---|
architecture/GOLDEN/ |
documentation/01_architecture/ |
The verified core. |
architecture/ADR_*.md |
documentation/03_technology/decisions/ |
Archive of decisions. |
architecture/SD_DEVOPS_*.md |
documentation/05_operations/ |
|
architecture/PERSONA_*.md |
documentation/06_product/personas/ |
|
architecture/reports/ |
documentation/08_security/audits/ |
|
architecture/TRASH/ |
DELETE | Clean start. |
4. Co-Location Strategy
We explicitly decide NOT to move README.md files that reside inside code directories (e.g., packages/ui/README.md).
* Code-Proximate Docs: stay with the code.
* System-Level Docs: go to the Library.