# prestomation/calendar-ripper architecture

> Architecture diagram of the GitHub repository prestomation/calendar-ripper, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/prestomation/calendar-ripper
- Repository: https://github.com/prestomation/calendar-ripper

## Overview

##### Project type and purpose
- This is a data-driven, plugin-based CLI tool that scrapes multiple calendar sources (HTML or JSON), generates standardized iCalendar (.ics) files, and aggregates them by tags.

##### Main components
a. **CLI Entry Point** (index.ts)
b. **Configuration Loader** (lib/config/loader.ts + schema.ts + sources/*.yaml)
c. **Ripper Base Classes** (HTMLRipper, JSONRipper in lib/config)
d. **Source-specific Rippers** (sources/<source>/ripper.ts)
e. **HTTP/Fetch Module** (built into the base rippers)
f. **Event Parser** (parseEvents implementations)
g. **Tag Aggregator** (lib/tag_aggregator.ts)
h. **ICS Generator & Template Renderer** (lib/calendar_ripper.ts + lib/templates/index.html)
i. **Output Store** (output .ics files + index.html)

##### Relationships & data flow
- The CLI loads configuration, discovers rippers under `sources/`, instantiates them, fetches HTML/JSON, parses events, hands results to the tag aggregator, then invokes the calendar generator to emit .ics and the HTML index.

##### Architectural patterns & principles
- **Plugin architecture**: each ripper folder is discovered dynamically.
- **Template method**: base classes define the scraping workflow; subclasses implement `parseEvents`.
- **Separation of concerns**: config parsing, scraping, event aggregation, and output generation are distinct modules.

##### Technologies & frameworks
- Node.js / TypeScript
- `@js-joda` for date/time
- `node-html-parser` for HTML scraping
- YAML config loader

## Diagram (Mermaid)

```mermaid
flowchart TB
  subgraph "CLI Entry Point"
    CLI["index.ts"]:::cli
  end

  subgraph "Configuration" 
    Loader["loader.ts"]:::config
    Schema["schema.ts"]:::config
    YAML["sources/external.yaml"]:::config
  end

  subgraph "Ripper Base Classes"
    HTMLBase["HTMLRipper"]:::base
    JSONBase["JSONRipper"]:::base
  end

  subgraph "Source-specific Rippers"
    RipperSrc["sources/<source>/ripper.ts"]:::sources
  end

  subgraph "Scraping & Parsing"
    Fetch["HTTP Fetch"]:::scrape
    Parse["parseEvents()"]:::scrape
  end

  subgraph "Tag Aggregation"
    Aggregator["tag_aggregator.ts"]:::agg
  end

  subgraph "ICS & HTML Generation"
    CalendarGen["calendar_ripper.ts"]:::gen
    Template["lib/templates/index.html"]:::gen
  end

  subgraph "File Output"
    ICSOut["output/*.ics"]:::output
    HTMLOut["output/index.html"]:::output
  end

  subgraph "Tests"
    TestCal["calendar_ripper.test.ts"]:::tests
    TestLoader["loader.test.ts"]:::tests
    TestURL["urlparse.test.ts"]:::tests
    TestAgg["tag_aggregator.test.ts"]:::tests
    TestSrc["sources/*/ripper.test.ts"]:::tests
  end

  CLI -->|loads config| Loader
  Loader --> Schema
  Loader --> YAML
  Loader --> RipperSrc
  RipperSrc --> HTMLBase
  RipperSrc --> JSONBase
  HTMLBase --> Fetch
  JSONBase --> Fetch
  Fetch --> Parse
  Parse --> Aggregator
  Aggregator --> CalendarGen
  CalendarGen --> Template
  CalendarGen --> ICSOut
  Template --> HTMLOut

  %% Tests Connections
  CalendarGen --> TestCal
  Loader --> TestLoader
  Loader --> TestURL
  Aggregator --> TestAgg
  RipperSrc --> TestSrc

  %% Click Events
  click CLI "https://github.com/prestomation/calendar-ripper/blob/main/index.ts"
  click Loader "https://github.com/prestomation/calendar-ripper/blob/main/lib/config/loader.ts"
  click Schema "https://github.com/prestomation/calendar-ripper/blob/main/lib/config/schema.ts"
  click YAML "https://github.com/prestomation/calendar-ripper/blob/main/sources/external.yaml"
  click HTMLBase "https://github.com/prestomation/calendar-ripper/blob/main/lib/config/htmlscrapper.ts"
  click JSONBase "https://github.com/prestomation/calendar-ripper/blob/main/lib/config/jsonscrapper.ts"
  click RipperSrc "https://github.com/prestomation/calendar-ripper/blob/main/sources/<source>/ripper.ts"
  click Aggregator "https://github.com/prestomation/calendar-ripper/blob/main/lib/tag_aggregator.ts"
  click CalendarGen "https://github.com/prestomation/calendar-ripper/blob/main/lib/calendar_ripper.ts"
  click Template "https://github.com/prestomation/calendar-ripper/blob/main/lib/templates/index.html"
  click TestCal "https://github.com/prestomation/calendar-ripper/blob/main/lib/calendar_ripper.test.ts"
  click TestLoader "https://github.com/prestomation/calendar-ripper/blob/main/lib/config/loader.test.ts"
  click TestURL "https://github.com/prestomation/calendar-ripper/blob/main/lib/config/urlparse.test.ts"
  click TestAgg "https://github.com/prestomation/calendar-ripper/blob/main/lib/tag_aggregator.test.ts"
  click TestSrc "https://github.com/prestomation/calendar-ripper/blob/main/sources/*/ripper.test.ts"

  %% Styles
  classDef cli fill:#f9f,stroke:#333,stroke-width:1px
  classDef config fill:#bbf,stroke:#333,stroke-width:1px
  classDef base fill:#bfb,stroke:#333,stroke-width:1px
  classDef sources fill:#fbb,stroke:#333,stroke-width:1px
  classDef scrape fill:#8dd,stroke:#333,stroke-width:1px
  classDef agg fill:#ffb,stroke:#333,stroke-width:1px
  classDef gen fill:#dcb,stroke:#333,stroke-width:1px
  classDef output fill:#ddd,stroke:#333,stroke-width:1px
  classDef tests fill:#fdd,stroke:#333,stroke-width:1px
```
