Architecture Docs¶
Philosophy
These docs are written to be comprehensive and navigable at the same time. We prefer compact, high-signal sections over fragmented notes, and we use callouts, emphasis, and direct links so readers can find key decisions quickly without hunting across pages.
Two Audiences, One Contract
The split in site navigation is intentional. User Docs describe workflows and practical operation; Architecture Docs define implementation boundaries, invariants, and extension contracts. Both tracks must remain consistent.
Source-of-Truth Rule
Architecture Docs and the Jest suite are the implementation authority. If behavior diverges from this section, treat it as a defect and raise it to maintainers immediately. Contributor updates must be precise: append or modify only the relevant parts instead of rewriting unrelated content.
Decision Matrix¶
| Question | Start Here | Related Deep Dive |
|---|---|---|
| Where does canonical state live and mutate? | EventCache Contract | Event Storage and Identifiers |
| How are internal events translated to FullCalendar? | FullCalendar Interop | Data Flow |
| How is provider behavior structured and extended? | Provider Architecture | Provider Blueprint |
| Where are feature-level policies documented? | Features Architecture | Timezone Architecture |
| How does ActivityWatch infer and persist intent blocks? | ActivityWatch Architecture | ActivityWatch Implementation |
| How does Chrono Analyser connect and scale insights? | Chrono Analyser Architecture | Insights Engine |
Scope¶
This section is concept-first and implementation-bound. It documents ownership, data movement, invariants, extension points, and verification policy. Provider-specific mechanics stay in their feature pages so this area remains the stable system contract.
Implementation Anchors¶
Event orchestration: src/core/EventCache.ts
In-memory indexes: src/core/EventStore.ts
Normalization pipeline: src/core/EventEnhancer.ts
Provider contract and routing: src/providers/Provider.ts, src/providers/ProviderRegistry.ts
View integration: src/ui/view.ts
Compact index: Overview · EventCache · Storage · Interop · Data Flow · Core Systems · Features · ActivityWatch · Providers · Chrono