How cloud-atlas-ai/obsidian-ics works
Project Type and Purpose
• This is an Obsidian Community Plugin written in TypeScript.
• Purpose: Fetch remote ICS calendar feeds (e.g., Google Calendar “Secret iCal URL”), parse events, and inject formatted event lists into Obsidian Daily Notes or expose them via plugin API for Dataview/Templater/Full-Calendar.
File Structure
• Top-level build & config:
• esbuild.config.mjs, tsconfig.json, package.json, release scripts, GitHub workflows.
• Source code in src/:
• IEvent.ts – Event data model interface
• icalUtils.ts – ICS fetch & parse logic
• main.ts – Obsidian Plugin class: command registration, settings loading, API exposure
• settings/ICSSettings.ts – data model for user calendars & formatting options
• settings/ICSSettingsTab.ts – UI for editing settings
• assets: styles.css
• types.d.ts for ambient declarations.
Extract Key Components
a. Obsidian Host Application
– The container that loads the plugin and provides the Plugin API.
b. Plugin Initialization & Settings
– ICSSettings (data store)
– ICSSettingsTab (UI pane)
c. Command & API Layer
– ICS: Import events command handler in main.ts
– getEvents(...) API method for other plugins
d. ICS Service
– icalUtils.ts: HTTP fetcher + ICS parser → produces IEvent objects
e. Event Model
– IEvent interface: { utime, time, summary, location, description, endTime … }
f. Output Renderer
– Markdown builder in main.ts or downstream (Dataview/Templater)
– Optionally passes events to Full-Calendar via its renderCalendar API
g. External Integrations
– Dataview, Templater, Full-Calendar plugins consume the plugin’s API
h. Build & Release Pipeline
– Node.js/npm → esbuild → dist/main.js → manifest.json
– GitHub Actions and scripts for version bump & publishing
Relationships & Data Flows
1. User opens Obsidian → Plugin loads via manifest.json
2. Settings UI (ICSSettingsTab) reads/writes ICSSettings
3. User triggers “ICS: Import events” command
4. Command handler reads current daily note date via Obsidian API
5. For each configured calendar URL:
• icalUtils fetches remote ICS file → parses into IEvent[]
6. Plugin formats events per calendar‐specific settings → writes markdown into the active note
7. Alternatively, external plugins call getEvents(date-range) → receive IEvent[] → render as they see fit
8. Build pipeline bundles code and pushes releases using GitHub Actions
Architectural Patterns & Principles
• Modular separation: settings UI vs. core logic vs. data model
• Observer/Command pattern: registers commands with Obsidian host
• Service abstraction: icalUtils encapsulates all ICS‐specific parsing/fetching
• Plugin API exposure: plugin acts as a reusable service for other plugins
• Build‐time pipeline: esbuild for bundling, semver/version bump for releases
Final Advice
• Be exhaustive: break the plugin into its logical modules, even if they’re in the same codebase.
• Both runtime flows (user commands, API calls) and development flows (build → bundle → publish).