Documentation system

This page describes the documentation architecture. The decision record is ADR-002: Documentation system.

Goals

1. Understand the codebase — topology, domains, and where to start in each app
2. Track decisions — ADRs with status, index, and review in PRs
3. Support AI-assisted coding — structured maps, invariants, and guardrails
4. Run locally — two separate browsable docs sites during development
5. Deploy with audience-appropriate access — public product help; org-only developer docs

Two separate sites

Product app users and engineers never share a docs deployment.

Site	App	Source in repo	Local URL	Production
Product help	apps/docs	docs/personal/, docs/business/	http://localhost:4321	docs.keepintracks.com (public)
Developer docs	apps/dev-docs	docs/developer/, docs/domains/, docs/adr/	http://localhost:4322	dev.keepintracks.com (Cloudflare Access)

The product help site uses route-scoped sidebars: /personal/ shows only personal content; /business/ shows only business content; / is a product chooser splash.

Information architecture

flowchart TB
  subgraph repo [Repository source of truth]
    AGENTS[AGENTS.md]
    ARCH[ARCHITECTURE.md]
    ADR[docs/adr/]
    DEV[docs/developer/]
    DOM[docs/domains/]
    PER[docs/personal/]
    BIZ[docs/business/]
    PUB[docs/public/]
    RULES[.cursor/rules/]
  end

  subgraph productSite [apps/docs]
    ProductBrowse[Product help site]
  end

  subgraph devSite [apps/dev-docs]
    DevBrowse[Developer docs site]
  end

  PER --> ProductBrowse
  BIZ --> ProductBrowse
  DEV --> DevBrowse
  DOM --> DevBrowse
  ADR --> DevBrowse

  ProductBrowse --> DocsHost[docs.keepintracks.com]
  DevBrowse --> DevHost[dev.keepintracks.com]
  DevHost --> Access[Cloudflare Access]

  AGENTS --> ADR
  AGENTS --> DOM
  AGENTS --> ARCH
  RULES --> AGENTS

Directory layout

keepintracks/
├── AGENTS.md                 # AI entry point — short, links out
├── ARCHITECTURE.md           # System design and phases
├── docs/
│   ├── adr/                  # Decision records + index
│   ├── developer/            # Engineering guides (this section)
│   ├── domains/              # Bounded contexts
│   ├── personal/             # Personal app end-user help (English)
│   ├── business/             # Business app end-user help (English)
│   ├── fr/                   # French translations (personal/, business/)
│   └── public/               # Marketing-safe product pages
├── apps/
│   ├── docs/                 # Product help Starlight → docs.keepintracks.com
│   └── dev-docs/             # Developer Starlight → dev.keepintracks.com
└── .cursor/rules/            # Cursor guardrails

Audience split

Audience	Location	Site	Public?
Engineers	docs/developer/, docs/domains/, docs/adr/	dev.keepintracks.com	No (GitHub org via Access)
Personal app users	docs/personal/	docs.keepintracks.com/personal	Yes
Business app users	docs/business/	docs.keepintracks.com/business	Yes
AI agents	AGENTS.md, .cursor/rules/, domain docs	—	No
Marketing / prospects	docs/public/, marketing site	keepintracks.com	Yes

Never expose internal ADRs or domain internals on the product help site. Never link developer docs from the product help site.

ADRs

See ADR index.

• One decision per file: YYYY-MM-DD-short-title.md
• Status: Proposed → Accepted → Deprecated / Superseded
• Update the index table when adding or changing status

Domain docs

Each file in docs/domains/ should include:

• Purpose — what the domain owns
• Does not own — explicit boundaries
• Key paths — where code lives (when apps exist)
• Data model — tables and tenant rules
• Invariants — rules that must not break
• Related ADRs — links

AI-assisted coding

AGENTS.md

Short map at repo root: read-first links, repo layout, hard rules, domain pointers.

.cursor/rules/

Durable, enforceable constraints (architecture, domains, documentation, security). Keep rules concise; link to docs/ for detail.

Per-app README

When apps are scaffolded, each app gets a README with:

• Purpose
• bun --filter <app> dev
• Env var names (not secrets)
• Main entrypoints
• Links to domain docs

Writing style

• Prefer explicit lists and tables over long prose
• Use Mermaid for flows
• One concept per page; cross-link instead of duplicating
• Note when to update the doc at the top of domain pages

Local docs sites

From the repository root:

bun install
bun docs:dev       # product help → http://localhost:4321
bun dev-docs:dev   # developer docs → http://localhost:4322

Build for production:

bun docs:build
bun dev-docs:build

Sync scripts copy markdown from docs/ into each app’s src/content/docs/ before dev/build. Edit source files in docs/ only — never edit synced copies. Files prefixed with _ are excluded.

Deployment

Site	Hostname	Access
Product help	docs.keepintracks.com	Public
Developer docs	dev.keepintracks.com	Cloudflare Access + GitHub org

Local development stays unauthenticated for both sites.

Maintenance

Update documentation when changing:

• Architecture or isolation boundaries
• Domain ownership
• APIs or contracts
• Onboarding or local dev workflows
• Security, compliance, or ADR-worthy decisions

Run bun docs:build and bun dev-docs:build before opening PRs that touch docs.