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 does the plugin achieve 0ms UI freezing & off-main-thread processing? | Performance & Web Workers | Core Systems |
| How does the plugin handle centralized, optimized searching, filtering, and sorting? | Event Filtering and Sorting | EventCache Contract |
| How are internal events translated to FullCalendar? | FullCalendar Interop | Data Flow |
| How do external plugins or scripts get safe API access? | API Architecture Index | API Overview / Recipes |
| How is provider behavior structured and extended? | Provider Architecture | Provider Blueprint |
| How does the Obsidian Tasks provider query and surgically edit files? | Tasks Provider Architecture | Global Query Filtering |
| 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 |
| How does the plugin scope and package stylesheets? | Styling Architecture & CSS Audit | System Overview |
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
Web Worker manager: src/workers/WorkerManager.ts
Centralized filtering & sorting: src/core/EventFilterSortEngine.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
API entry points & bouncer: src/api/PublicAPI.ts, src/api/LocalServer.ts
Internal API dispatcher: src/api/InternalAPI.ts
View integration: src/ui/view.ts
Compact index: Overview · EventCache · Performance · Filtering & Sorting · Storage · Interop · API Index · Data Flow · Core Systems · Features · ActivityWatch · Providers · Chrono · Styling