System Overview

System MOC

This page is the map of content for the System architecture fold. Use it to jump directly to the contract page you need, instead of scanning all architecture docs linearly.

Quick Router (System Fold)

If you need to understand...	Start here
Event-state ownership and mutation authority	EventCache Contract
In-memory indexing and identifier mapping	Event Storage and Identifiers
OFCEvent <-> FullCalendar conversion boundary	FullCalendar Interop
External plugin API design and authorization	API Architecture
How to integrate another plugin via API	API Integration Blueprint
Runtime flow (load, mutate, external sync, tick/reminders)	Data Flow
Core subsystem contracts and invariants	Core Systems
Event-domain architecture scope	Events Architecture
Safe extension workflow	Extending the Plugin
Verification policy and docs-test alignment	Testing and Validation

Layer Model (At a Glance)

Layer	Responsibility	Must Not Own
UI Layer	Capture user intent and render current state through views/modals.	Canonical state mutation rules.
Presentation Layer	Apply workspace/view shaping and display-level overrides.	Provider I/O and persistence logic.
Core Layer	Own event lifecycle, indexing, normalization, recurrence, and time-aware behavior.	Provider-specific protocol details.
Provider Layer	Translate shared contracts into local/remote source reads and writes.	UI-specific decision making.
Adapter Layer	Isolate Obsidian APIs behind testable abstractions.	Cross-module business rules.

graph TD
    subgraph UI ["UI Layer"]
        View["CalendarView + React UI"]
    end

    subgraph Presentation ["Presentation Layer"]
        VE["ViewEnhancer (Filtering/VM)"]
    end

    subgraph Core ["Core Layer (Single Source of Truth)"]
        EC["EventCache (Orchestrator)"]
        ES["EventStore (In-Memory Index)"]
        EE["EventEnhancer (Data Transformer)"]
    end

    subgraph Provider ["Provider Layer"]
        PR["ProviderRegistry (I/O Hub)"]
        LP["Local Providers"]
        RP["Remote Providers"]
    end

    subgraph Adapter ["Adapter Layer"]
        OA["ObsidianAdapter"]
    end

    subgraph External ["External Systems"]
        Vault["Obsidian Vault APIs"]
        Net["Internet (Google/CalDAV)"]
    end

    %% Flow: User Action
    View -- "CRUD Ops" --> EC
    EC -- "Query/Index" --> ES
    EC -- "Normalize" --> EE
    EC -- "Dispatch I/O" --> PR

    %% Flow: Storage
    PR --> LP
    PR --> RP
    LP -- "File Ops" --> OA
    OA -- "Sync" --> Vault
    RP -- "Remote Sync" --> Net

    %% Flow: Notifications
    EC -. "Pub/Sub Update" .-> VE
    VE -. "Reactive Refresh" .-> View

    classDef core fill:#f9f,stroke:#333,stroke-width:2px;
    classDef provider fill:#bbf,stroke:#333,stroke-width:1px;
    class EC,ES,EE core;
    class PR,LP,RP provider;

Stable Entry Points

Bootstrap and composition: src/main.ts
State owner and orchestration: src/core/EventCache.ts
Storage and indexing: src/core/EventStore.ts
Provider routing: src/providers/ProviderRegistry.ts
Workspace/view shaping: src/core/ViewEnhancer.ts