README.md

Docs

Internal documentation for engineers and agents working in the Compass repo.

Start with AGENTS.md for repo rules and command defaults. Use this index for codebase shape, subsystem behavior, and acceptance runbooks.

How docs get published

Markdown files in this docs/ directory are automatically mirrored to docs.compasscalendar.com. A GitHub Action detects any push to main that touches docs/** and syncs the changes to the doc site. Just edit any of the markdown in docs/ and the doc site will update itself upon merge.

Start Here

• Repo Architecture
• Feature File Map
• Common Change Recipes

Common Change Paths

• Auth or session behavior: Frontend Runtime Flow, Password Auth Flow, Google Sync And SSE Flow
• Event shape or recurrence behavior: Event And Task Domain Model, Recurrence Handling
• Local-first or storage behavior: Offline Storage And Migrations
• Backend routes and API behavior: Backend Route Map, Backend Request Flow, Backend Error Handling

Runtime Flows

• Frontend Runtime Flow
• Google Sync And SSE Flow
• Password Auth Flow

Architecture And Domain

• Repo Architecture
• Event And Task Domain Model
• Glossary

Development And Operations

• Local Development
• Hosting Modes
• Self-Hosting
• Testing Playbook
• Types And Validation
• CLI And Maintenance Commands
• Deploy

Feature Deep Dives

• Password Auth Flow
• Google Sync And SSE Flow
• Recurrence Handling
• Offline Storage And Migrations

Acceptance

User-visible behavior runbooks for manual verification and expected outcomes:

• Auth
• Events
• Google Sync
• Recurring Events
• Shortcuts
• Tasks