Documentation Index

Documentation Index

This is the canonical entrypoint for all repository documentation.

Start here. Architecture, runbooks, ADRs, active plans, and archives are all organized below. See PLACEMENT-GUIDE.md for where to add new documents.

---

Architecture

Authoritative architecture docs for the monorepo. These are the source of truth for code placement, package categories, dependency rules, and structural patterns.

Doc	Purpose
00-repo-map.md	Full repo layout and ownership map
01-code-placement.md	Where code belongs
02-package-categories.md	Package taxonomy
03-dependency-rules.md	Cross-package dependency constraints
04-dashboard-structure.md	Dashboard app internals
05-worker-structure.md	Worker app internals
06-current-gaps.md	Known architecture gaps (living backlog)
07-feature-source-of-truth.md	Feature ownership source-of-truth
08-feature-internals.md	Feature package internals
09-tanstack-query-patterns.md	TanStack Query patterns
10-domain-packages.md	Domain package design
11-cloudflare-runtime-boundary.md	Cloudflare runtime constraints
12-generated-artifacts.md	Generated artifact rules
13-naming-conventions.md	Naming standards (canonical)
14-barrel-rules.md	Barrel export rules
15-architecture-checks.md	CI architecture checks — how to run, what they enforce, and what to do when they fail
16-contributing-and-templates.md	Contributor workflow, guardrails, and scaffold entrypoints

Template examples live in architecture/templates/README.md.

---

Onboarding

Start here if you are new to the repo.

Doc	Purpose
onboarding/new-contributors.md	First-day workflow, common commands, repo mental model

---

ADRs

Architectural Decision Records for durable decisions that affect the repo.

Doc	Purpose
0002-dashboard-route-composition.md	Historical route composition decision (superseded)

New ADRs follow NNNN-short-slug.md naming in docs/adr/.

---

Runbooks

Operational procedures, rollout guides, incident playbooks, and troubleshooting docs. Everything needed to operate and release the system.

Doc	Purpose
glitchtip-monitoring.md	GlitchTip / Sentry monitoring setup
slow-db-query-runbook.md	Slow DB query detection and response
integrations-api-rollout.md	Integrations API rollout and rollback
workspace-modules-rollout.md	Workspace module gating rollout
eventbus/backfill-runbook.md	Event bus historical backfill procedure
eventbus/incident-playbook.md	Event bus incident response playbook
eventbus/phase-2-rollout-checklist.md	Event bus phase 2 rollout checklist
eventbus/operations-slo.md	Event bus SLO targets

---

Plans

Active future implementation plans and tracked initiatives.

Doc	Purpose
sentrydbqueries/README.md	Slow DB query observability plan

---

Reference

Stable technical reference for system components and subsystems.

Doc	Purpose
workspace-api-key-management.md	Workspace API key system reference

---

App-Local and Package-Local Docs

Some documentation lives near the code it describes. These are explicitly maintained as local exceptions and linked here for discoverability.

Location	Contents	Why local
apps/dashboard/AGENTS.md	Dashboard-specific agent operational guidance	Tightly coupled to dashboard internals
apps/dashboard/ARCHITECTURE.md	Dashboard app architecture detail	App-local architecture supplement
apps/dashboard/docs/CSRF_PROTECTION.md	CSRF protection details	Implementation detail for dashboard only
apps/dashboard/docs/ENABLING_DEBUG_IN_PRODUCTION.md	Debug flag usage	Dashboard-specific operational note
tests/AGENTS.md	E2E test harness guide	Tightly coupled to test runner internals

---

Non-Canonical Areas

These areas exist but are not authoritative documentation:

Area	Status	Notes
thoughts/	Non-canonical working notes	Informal scratch area only
plans/ (root)	Deprecated	Active plans live in docs/plans/; root plans/ is legacy and should not receive edits

---

See PLACEMENT-GUIDE.md for where to add new documents. See architecture/16-contributing-and-templates.md for how to add new code.