# beta-sdc/calendar architecture

> Architecture diagram of the GitHub repository beta-sdc/calendar, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/beta-sdc/calendar
- Repository: https://github.com/beta-sdc/calendar

## Overview

BETA-SDC Calendar turns maintained one-event ICS files into scope- and period-specific subscription feeds and a Pages site. The principal workflow is event authoring, validation and feed/site generation, followed by user selection or browsing of calendar links. The web interface also exposes individual-event downloads and subscription URLs; Outlook guidance is documented separately. The generator excerpt is partial, so links for stages not shown directly are included only where the README documents them.

Main entry points: [`scripts/build_feeds.py`](https://github.com/beta-sdc/calendar/blob/main/scripts/build_feeds.py) (Validate and Build), [`web/app.js`](https://github.com/beta-sdc/calendar/blob/main/web/app.js) (Subscription UI), [`web/events.js`](https://github.com/beta-sdc/calendar/blob/main/web/events.js) (Event Browser UI), [`public`](https://github.com/beta-sdc/calendar/tree/main/public) (Public ICS Events)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_sources["Event Sources"]
  node_public_events["Public ICS Events"]
  node_internal_events["Internal ICS Events"]
end

subgraph group_generation["Feed Generation"]
  node_feed_builder["Validate and Build<br/>[build_feeds.py]"]
  node_aggregate_feeds["Aggregate ICS Feeds<br/>[build_feeds.py]"]
  node_feed_metadata["Feed Metadata<br/>[build_feeds.py]"]
  node_event_metadata["Event Metadata<br/>[build_feeds.py]"]
  node_individual_ics["Published Event ICS"]
end

subgraph group_subscription["Subscriptions"]
  node_subscription_page["Feed Selector<br/>[index.html]"]
  node_subscription_logic["Subscription UI<br/>[app.js]"]
end

subgraph group_events["Event Browser"]
  node_events_page["Single Event Page<br/>[events.html]"]
  node_events_logic["Event Browser UI<br/>[events.js]"]
end

subgraph group_guidance["User Guidance"]
  node_email_guide["Email Link Guide"]
  node_outlook_guide["Outlook Guide<br/>[README.md]"]
end

node_event_editor(("Calendar Maintainers"))
node_subscription_user(("Calendar Subscribers"))
node_calendar_apps(("Calendar Applications"))
node_event_user(("Event Browsers"))
node_email_sender(("Email Authors"))

node_event_editor -->|"maintains"| node_public_events
node_event_editor -->|"maintains"| node_internal_events
node_public_events -->|"validates"| node_feed_builder
node_internal_events -->|"validates"| node_feed_builder
node_feed_builder -->|"generates"| node_aggregate_feeds
node_feed_builder -->|"generates"| node_feed_metadata
node_feed_builder -->|"generates"| node_event_metadata
node_feed_builder -->|"copies"| node_individual_ics
node_subscription_user -->|"opens"| node_subscription_page
node_subscription_page -->|"runs"| node_subscription_logic
node_subscription_logic -->|"fetches"| node_feed_metadata
node_subscription_logic -->|"offers feed links"| node_calendar_apps
node_subscription_logic -->|"offers downloads"| node_subscription_user
node_calendar_apps -->|"subscribes"| node_aggregate_feeds
node_event_user -->|"opens"| node_events_page
node_events_page -->|"runs"| node_events_logic
node_events_logic -->|"fetches"| node_event_metadata
node_events_logic -->|"links to"| node_individual_ics
node_event_user -->|"consults"| node_email_guide
node_email_sender -->|"follows"| node_email_guide
node_subscription_user -.->|"consults"| node_outlook_guide
node_outlook_guide -.->|"guides setup"| node_calendar_apps

click node_public_events "https://github.com/beta-sdc/calendar/tree/main/public"
click node_internal_events "https://github.com/beta-sdc/calendar/tree/main/internal"
click node_feed_builder "https://github.com/beta-sdc/calendar/blob/main/scripts/build_feeds.py"
click node_aggregate_feeds "https://github.com/beta-sdc/calendar/blob/main/scripts/build_feeds.py"
click node_feed_metadata "https://github.com/beta-sdc/calendar/blob/main/scripts/build_feeds.py"
click node_event_metadata "https://github.com/beta-sdc/calendar/blob/main/scripts/build_feeds.py"
click node_individual_ics "https://github.com/beta-sdc/calendar/tree/main/public"
click node_subscription_page "https://github.com/beta-sdc/calendar/blob/main/web/index.html"
click node_subscription_logic "https://github.com/beta-sdc/calendar/blob/main/web/app.js"
click node_events_page "https://github.com/beta-sdc/calendar/blob/main/web/events.html"
click node_events_logic "https://github.com/beta-sdc/calendar/blob/main/web/events.js"
click node_email_guide "https://github.com/beta-sdc/calendar/blob/main/docs/email-calendar-links.md"
click node_outlook_guide "https://github.com/beta-sdc/calendar/blob/main/outlook-subscription-guide/README.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_public_events,node_internal_events,node_event_user toneBlue
class node_feed_builder,node_aggregate_feeds,node_feed_metadata,node_event_metadata,node_individual_ics toneAmber
class node_subscription_page,node_subscription_logic toneMint
class node_events_page,node_events_logic toneRose
class node_email_guide,node_outlook_guide,node_event_editor,node_subscription_user,node_calendar_apps,node_email_sender toneIndigo
```

## Components

### Event Sources

- [Public ICS Events](https://github.com/beta-sdc/calendar/tree/main/public): `public`
- [Internal ICS Events](https://github.com/beta-sdc/calendar/tree/main/internal): `internal`

### Feed Generation

- [Validate and Build](https://github.com/beta-sdc/calendar/blob/main/scripts/build_feeds.py): `scripts/build_feeds.py`
- [Aggregate ICS Feeds](https://github.com/beta-sdc/calendar/blob/main/scripts/build_feeds.py): `scripts/build_feeds.py`
- [Feed Metadata](https://github.com/beta-sdc/calendar/blob/main/scripts/build_feeds.py): `scripts/build_feeds.py`
- [Event Metadata](https://github.com/beta-sdc/calendar/blob/main/scripts/build_feeds.py): `scripts/build_feeds.py`
- [Published Event ICS](https://github.com/beta-sdc/calendar/tree/main/public): `public`

### Subscriptions

- [Feed Selector](https://github.com/beta-sdc/calendar/blob/main/web/index.html): `web/index.html`
- [Subscription UI](https://github.com/beta-sdc/calendar/blob/main/web/app.js): `web/app.js`

### Event Browser

- [Single Event Page](https://github.com/beta-sdc/calendar/blob/main/web/events.html): `web/events.html`
- [Event Browser UI](https://github.com/beta-sdc/calendar/blob/main/web/events.js): `web/events.js`

### User Guidance

- [Email Link Guide](https://github.com/beta-sdc/calendar/blob/main/docs/email-calendar-links.md): `docs/email-calendar-links.md`
- [Outlook Guide](https://github.com/beta-sdc/calendar/blob/main/outlook-subscription-guide/README.md): `outlook-subscription-guide/README.md`

### Other components

- **Calendar Maintainers**
- **Calendar Subscribers**
- **Calendar Applications**
- **Event Browsers**
- **Email Authors**

## Connections

- Calendar Maintainers → Public ICS Events: maintains
- Calendar Maintainers → Internal ICS Events: maintains
- Public ICS Events → Validate and Build: validates
- Internal ICS Events → Validate and Build: validates
- Validate and Build → Aggregate ICS Feeds: generates
- Validate and Build → Feed Metadata: generates
- Validate and Build → Event Metadata: generates
- Validate and Build → Published Event ICS: copies
- Calendar Subscribers → Feed Selector: opens
- Feed Selector → Subscription UI: runs
- Subscription UI → Feed Metadata: fetches
- Subscription UI → Calendar Applications: offers feed links
- Subscription UI → Calendar Subscribers: offers downloads
- Calendar Applications → Aggregate ICS Feeds: subscribes
- Event Browsers → Single Event Page: opens
- Single Event Page → Event Browser UI: runs
- Event Browser UI → Event Metadata: fetches
- Event Browser UI → Published Event ICS: links to
- Event Browsers → Email Link Guide: consults
- Email Authors → Email Link Guide: follows
- Calendar Subscribers → Outlook Guide: consults
- Outlook Guide → Calendar Applications: guides setup