ADR-002: Documentation system

ADR-002: Documentation system and ADR process

Status: Accepted
Date: 2026-05-28
Deciders: Keepin’ Tracks engineering
Supersedes: —
Superseded by: —

Context

The repository needs documentation that:

Helps engineers understand architecture and domain boundaries
Records durable decisions (ADRs) as the codebase grows
Gives AI-assisted coding tools structured, accurate context
Runs locally during development
Can later be deployed behind organization-only access

Scattered wikis, Notion pages, or docs divorced from the repo make PR review and AI indexing harder.

Decision

Adopt docs-as-code in the repository with two separate Starlight sites — one for product app users (personal and business), one for engineers.

Source of truth

Path	Audience	Purpose
`docs/personal/`	Personal app users	End-user help and guides
`docs/business/`	Business app users	End-user help and guides
`docs/adr/`	Engineering	Architecture Decision Records
`docs/developer/`	Engineering	Onboarding, runbooks, tooling, doc system
`docs/domains/`	Engineering	Bounded contexts, ownership, invariants
`docs/public/`	Prospects	Marketing-safe product pages
`ARCHITECTURE.md`	Engineering	System topology and phased delivery
`AGENTS.md`	AI + engineering	Short orientation map for agents
`.cursor/rules/`	AI (Cursor)	Enforceable guardrails

Docs sites

Site	App	Source	Production
Product help	`apps/docs`	`docs/personal/`, `docs/business/`	`docs.keepintracks.com` (public; `/personal/`, `/business/` sections)
Developer docs	`apps/dev-docs`	`docs/developer/`, `docs/domains/`, `docs/adr/`	`dev.keepintracks.com` (Cloudflare Access)

Local: bun docs:dev (port 4321), bun dev-docs:dev (port 4322). Sync scripts copy markdown before dev/build.

ADR process

Filename: YYYY-MM-DD-short-title.md
Index: docs/adr/index.md
Template: docs/adr/_template.md
Required for major architecture, security, compliance, tenant isolation, accounting, and infra decisions

AI-assisted coding

AGENTS.md at repo root links to architecture, ADRs, and domain docs
Domain docs name key paths, invariants, and what each domain does not own
Per-app README.md files (when apps exist) describe entrypoints and local run commands
Cursor rules stay short; detailed prose lives in docs/

Deployment

apps/docs → Cloudflare Pages at docs.keepintracks.com (public)
apps/dev-docs → Cloudflare Pages at dev.keepintracks.com with Cloudflare Access (GitHub org)

Local development remains unauthenticated for both sites.

Consequences

Positive

Single source of truth in git; docs reviewed in PRs
ADRs are discoverable and linked from architecture docs
Starlight gives search, sidebar, and Mermaid support
Fits Cloudflare-native deployment path
AI tools can index markdown in-repo