Entry point for engineers (and coding agents) working in this repo. For the user-facing overview read the repo README.md. For day-to-day working rules (worktrees, SOLID, testing checklist, production safety) read CLAUDE.md.
| If you want to… | Go to |
|---|---|
| Understand what a feature does and where it lives in code | features/ |
| Understand the system shape (monorepo, data flow, envs) | architecture/ |
| Run tests, builds, releases, migrations, or set up a box | operations/ |
| Understand why a technology / pattern was chosen | adr/ |
| Read historical plans (completed, superseded — do not use) | archive/ |
One brief per functional area. Each brief lists the current state, code paths on every platform, related ADRs, and how to verify a change.
features/auth.md— email/password + OAuth, approval flow, RLS boundaryfeatures/notes-and-notebooks.md— data model, CRUD API, soft delete, trashfeatures/editor.md— BlockNote editor, auto-save, Markdown conversionfeatures/offline-sync.md— WatermelonDB on mobile + desktop, sync loop, conflict rulesfeatures/search.md— full-text search across notesfeatures/evernote-import.md—.enexparsing and import pipelinefeatures/mcp-server.md— remote MCP at/api/mcp, API keys, tool reference, registryfeatures/design-system.md— tokens, primitives, cross-platform parityfeatures/email-and-approval.md— transactional email via Resend + approval pipelinefeatures/mobile-desktop-apps.md— how iOS / Android / macOS fit together
architecture/overview.md— monorepo map, platform parity rules, data flowarchitecture/environments.md— dev / prod Supabase projects, migration workflowarchitecture/testing.md— test matrix by platform and test type
operations/local-dev-setup.md— first-time machine setupoperations/builds-and-releases.md— Fastlane for iOS / Android / macOS, versioning, release notesoperations/migrations.md— Supabase migration workflow, production safety rails
See adr/README.md for the full index. An append-only decision log.
- Features docs follow a fixed template (status, current state, code paths, ADRs, cross-platform notes, modifying safely, verify). Keep them navigational — link to ADRs for rationale, link to operations for commands; do not repeat.
- ADRs are append-only. If a decision reverses, file a new ADR and mark the old one
Superseded by NNNN. - Historical plans live in
archive/. Never edit archived content; never treat it as source of truth.