# cloud-atlas-ai/obsidian-ics architecture

> Architecture diagram of the GitHub repository cloud-atlas-ai/obsidian-ics, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cloud-atlas-ai/obsidian-ics
- Repository: https://github.com/cloud-atlas-ai/obsidian-ics

## Overview

##### 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).

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Obsidian Host" 
        ObsidianHost["Obsidian Host (manifest.json)"]:::host
    end

    subgraph "ICS Plugin Internals"
        subgraph "Settings"
            ICSSettingsUI["ICSSettingsTab"]:::plugin
            ICSSettingsStore["ICSSettings"]:::plugin
        end
        subgraph "Core"
            Main["Main Plugin (main.ts)"]:::plugin
            IcalService["ICS Service (icalUtils.ts)"]:::plugin
            EventModel["Event Model (IEvent)"]:::plugin
            Types["Ambient Types"]:::plugin
        end
        subgraph "Output"
            NoteFile["Daily Note"]:::plugin
        end
    end

    subgraph "External Services"
        ExternalICS["Remote ICS URL"]:::external
    end

    subgraph "External Plugins"
        ExternalPluginDV["Dataview"]:::external
        ExternalPluginTP["Templater"]:::external
        ExternalPluginFC["Full-Calendar"]:::external
    end

    subgraph "Build & CI/CD"
        BuildConfig["esbuild.config.mjs"]:::build
        ReleaseSH["release.sh"]:::build
        ReleaseBeta["release-beta.sh"]:::build
        VersionBump["version-bump.mjs"]:::build
        CI["GitHub Actions"]:::build
    end

    ObsidianHost -->|"loads plugin via manifest"| Main
    Main -->|"opens UI"| ICSSettingsUI
    ICSSettingsUI -->|"read/write settings"| ICSSettingsStore
    ICSSettingsStore -->|"provides config to"| Main
    Main -->|"invokes fetch/parse"| IcalService
    IcalService -->|"fetch ICS"| ExternalICS
    IcalService -->|"parse → IEvent[]"| EventModel
    EventModel -->|"model provided to"| Main
    Types -->|"type declarations used by"| Main
    Main -->|"write markdown"| NoteFile
    Main -->|"expose getEvents API"| ExternalPluginDV
    Main -->|"expose getEvents API"| ExternalPluginTP
    Main -->|"expose getEvents API"| ExternalPluginFC

    Main -->|"bundles with"| BuildConfig
    BuildConfig -->|"packaged by"| CI
    CI -->|"runs release scripts"| ReleaseSH
    CI -->|"runs release scripts"| ReleaseBeta
    CI -->|"runs release scripts"| VersionBump

    click ObsidianHost "https://github.com/cloud-atlas-ai/obsidian-ics/blob/master/manifest.json"
    click EventModel "https://github.com/cloud-atlas-ai/obsidian-ics/blob/master/src/IEvent.ts"
    click IcalService "https://github.com/cloud-atlas-ai/obsidian-ics/blob/master/src/icalUtils.ts"
    click ICSSettingsStore "https://github.com/cloud-atlas-ai/obsidian-ics/blob/master/src/settings/ICSSettings.ts"
    click ICSSettingsUI "https://github.com/cloud-atlas-ai/obsidian-ics/blob/master/src/settings/ICSSettingsTab.ts"
    click Main "https://github.com/cloud-atlas-ai/obsidian-ics/blob/master/src/main.ts"
    click Types "https://github.com/cloud-atlas-ai/obsidian-ics/blob/master/types.d.ts"
    click BuildConfig "https://github.com/cloud-atlas-ai/obsidian-ics/blob/master/esbuild.config.mjs"
    click ReleaseSH "https://github.com/cloud-atlas-ai/obsidian-ics/blob/master/release.sh"
    click ReleaseBeta "https://github.com/cloud-atlas-ai/obsidian-ics/blob/master/release-beta.sh"
    click VersionBump "https://github.com/cloud-atlas-ai/obsidian-ics/blob/master/version-bump.mjs"
    click CI "https://github.com/cloud-atlas-ai/obsidian-ics/blob/master/.github/workflows/release.yml"

    classDef host fill:#f0f0f0,stroke:#333,stroke-width:1px
    classDef plugin fill:#cfe2ff,stroke:#0b5394,stroke-width:1px
    classDef external fill:#d9ead3,stroke:#38761d,stroke-width:1px
    classDef build fill:#f9cb9c,stroke:#e69138,stroke-width:1px
```
