Skip to content

API Architecture

Philosophy

These docs provide a comprehensive, high-density, and navigable source of truth for the Full Calendar Remastered developer API and local REST server. We prioritize precise contracts, compact reference tables, code-anchored invariants, and direct hyperlinking so maintainers and third-party developers can build, integrate, and verify programmatic interfaces quickly.

Two Audiences, One Contract

  • User Feature Documentation: Explains UI setup, Personal Access Token generation, basic cURL/DataviewJS code snippets, and security toggles.
  • API Architecture Docs: Defines exact component boundaries, permission scope checks, REST endpoint schemas, authorization modal lifecycles, and InternalAPI execution contracts. Both tracks must remain synchronized.

Security & Process Invariants

The API layer MUST enforce strict capability-gated authorization on all entry points. The local HTTP listener binds strictly to 127.0.0.1 on desktop environments and disables itself on mobile. State mutations MUST route through EventCache or ProviderRegistry to preserve vault integrity.

Decision Matrix

Question Start Here Related Deep Dive
What is the overall API architecture and system flow? Overview Data Flow
How do in-vault plugins call the JavaScript API? Public JS API Recipes & Integration Blueprints
How do external scripts or CLI tools query/mutate via HTTP? REST Server Specification Recipes & Integration Blueprints
What permission scopes exist and how are tokens validated? Scopes & Permissions Public JS API
How does InternalAPI translate API calls into cache & view actions? Internal API Engine EventCache Contract
How do I write DataviewJS, Templater, or Python recipes? Recipes & Integration Blueprints User API Feature Guide

Component Scope Map

Component Class / Entry Point Responsibility Key File Anchor
Public API PublicAPI Exposed on app.plugins.plugins['full-calendar'].api. Manages requestAccess() modal prompts and withToken() capability verification. src/api/PublicAPI.ts
Authorized API AuthorizedAPI Capability-wrapped interface returned by withToken(). Enforces per-method scope assertions. src/api/PublicAPI.ts
REST Server LocalServer Local Node.js HTTP listener (127.0.0.1:${port}). Intercepts Bearer token requests and routes to AuthorizedAPI. src/api/LocalServer.ts
Internal Engine InternalAPI Unexposed engine executing workspace leaf focus, view changing, modal creation, and event querying. src/api/InternalAPI.ts
Scope System apiScopes Normalizes scope arrays (normalizeApiScopes), verifies scope grants (hasApiScope), defines FULL_ACCESS_SCOPE. src/api/apiScopes.ts
Auth Modal AuthorizationModal User-facing consent modal shown when an Obsidian plugin invokes requestAccess(). src/api/AuthorizationModal.ts

Architectural Rules & Invariants

  1. Bouncer Boundary: Neither PublicAPI nor LocalServer may directly mutate cache state or bypass scope evaluation. All operations MUST be validated through withToken() or assertScope().
  2. Localhost Isolation: LocalServer MUST bind exclusively to IPv4 127.0.0.1. Remote binding or network exposure is strictly forbidden.
  3. Platform Safety: On mobile environments (iOS/Android Capacitor), LocalServer.start() MUST NOT instantiate Node.js http listeners to prevent runtime exceptions.
  4. Canonical State Authority: All event additions, edits, deletions, and moves MUST execute through EventCache methods (addEvent, updateEventWithId, deleteEvent, moveEventToCalendar), never by directly modifying memory structures.

Implementation Anchors

Compact index: Overview · Public JS API · REST Server · Scopes & Permissions · Internal API · Recipes & Blueprints · System Index