# eshwarmuthusamy/klaxon architecture

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

- Interactive diagram: https://gitdiagram.com/eshwarmuthusamy/klaxon
- Repository: https://github.com/eshwarmuthusamy/klaxon

## Overview

Klaxon is a local macOS meeting-alert daemon: it polls the synced Calendar app, detects eligible upcoming events, and presents a persistent audible alert until dismissed, joined, or the meeting ends. The main orchestration lives in the poller; calendar parsing, alert presentation, configuration, and deduplication state are separate runtime layers. The README documents the Chrome/Edge kiosk and dialog fallback; the sampled alert source confirms both paths. The graph omits setup and launch-agent mechanics, which are deployment rather than product runtime.

Main entry points: [`src/localAlert.js`](https://github.com/eshwarmuthusamy/klaxon/blob/main/src/localAlert.js) (Alert coordinator), [`src/index.js`](https://github.com/eshwarmuthusamy/klaxon/blob/main/src/index.js) (Poll orchestrator), [`src/config.js`](https://github.com/eshwarmuthusamy/klaxon/blob/main/src/config.js) (Settings), [`src/localCalendar.js`](https://github.com/eshwarmuthusamy/klaxon/blob/main/src/localCalendar.js) (Calendar reader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_polling["Event polling"]
  node_poller["Poll orchestrator<br/>[index.js]"]
end

subgraph group_calendar["Calendar access"]
  node_calendar_reader["Calendar reader<br/>[localCalendar.js]"]
  node_icalbuddy["icalBuddy"]
end

subgraph group_alerts["Alert experience"]
  node_alert_service["Alert coordinator<br/>[localAlert.js]"]
  node_alert_page["Kiosk page and server<br/>[localAlert.js]"]
  node_browser["Chrome or Edge"]
  node_dialog["macOS dialog"]
  node_sound["afplay sound loop"]
  node_meeting["Meeting link"]
end

subgraph group_runtime["Runtime support"]
  node_config["Settings<br/>[config.js]"]
  node_alert_state[("Alert state<br/>[state.js]")]
end

node_user(("Mac user"))

node_poller -->|"fetches events"| node_calendar_reader
node_calendar_reader -->|"reads calendar"| node_icalbuddy
node_poller -->|"loads and saves"| node_alert_state
node_poller -->|"starts alert"| node_alert_service
node_poller -->|"reads settings"| node_config
node_alert_service -->|"reads sound settings"| node_config
node_alert_state -->|"uses state path"| node_config
node_alert_service -->|"serves kiosk alert"| node_alert_page
node_alert_service -->|"launches isolated kiosk"| node_browser
node_alert_service -->|"falls back to dialog"| node_dialog
node_alert_service -->|"starts and stops loop"| node_sound
node_alert_service -->|"opens on join"| node_meeting
node_user -->|"dismisses or joins"| node_alert_page
node_user -.->|"dismisses or joins"| node_dialog

click node_poller "https://github.com/eshwarmuthusamy/klaxon/blob/main/src/index.js"
click node_calendar_reader "https://github.com/eshwarmuthusamy/klaxon/blob/main/src/localCalendar.js"
click node_config "https://github.com/eshwarmuthusamy/klaxon/blob/main/src/config.js"
click node_alert_state "https://github.com/eshwarmuthusamy/klaxon/blob/main/src/state.js"
click node_alert_service "https://github.com/eshwarmuthusamy/klaxon/blob/main/src/localAlert.js"
click node_alert_page "https://github.com/eshwarmuthusamy/klaxon/blob/main/src/localAlert.js"

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_poller,node_user toneBlue
class node_calendar_reader,node_icalbuddy toneAmber
class node_alert_service,node_alert_page,node_browser,node_dialog,node_sound,node_meeting toneMint
class node_config,node_alert_state toneRose
```

## Components

### Event polling

- [Poll orchestrator](https://github.com/eshwarmuthusamy/klaxon/blob/main/src/index.js): `src/index.js`

### Calendar access

- [Calendar reader](https://github.com/eshwarmuthusamy/klaxon/blob/main/src/localCalendar.js): `src/localCalendar.js`
- **icalBuddy**

### Alert experience

- [Alert coordinator](https://github.com/eshwarmuthusamy/klaxon/blob/main/src/localAlert.js): `src/localAlert.js`
- [Kiosk page and server](https://github.com/eshwarmuthusamy/klaxon/blob/main/src/localAlert.js): `src/localAlert.js`
- **Chrome or Edge**
- **macOS dialog**
- **afplay sound loop**
- **Meeting link**

### Runtime support

- [Settings](https://github.com/eshwarmuthusamy/klaxon/blob/main/src/config.js): `src/config.js`
- [Alert state](https://github.com/eshwarmuthusamy/klaxon/blob/main/src/state.js): `src/state.js`

### Other components

- **Mac user**

## Connections

- Poll orchestrator → Calendar reader: fetches events (evidence: `src/index.js`)
- Calendar reader → icalBuddy: reads calendar (evidence: `src/localCalendar.js`)
- Poll orchestrator → Alert state: loads and saves (evidence: `src/index.js`)
- Poll orchestrator → Alert coordinator: starts alert (evidence: `src/index.js`)
- Poll orchestrator → Settings: reads settings (evidence: `src/index.js`)
- Alert coordinator → Settings: reads sound settings (evidence: `src/localAlert.js`)
- Alert state → Settings: uses state path (evidence: `src/state.js`)
- Alert coordinator → Kiosk page and server: serves kiosk alert (evidence: `src/localAlert.js`)
- Alert coordinator → Chrome or Edge: launches isolated kiosk (evidence: `src/localAlert.js`)
- Alert coordinator → macOS dialog: falls back to dialog (evidence: `src/localAlert.js`)
- Alert coordinator → afplay sound loop: starts and stops loop (evidence: `src/localAlert.js`)
- Alert coordinator → Meeting link: opens on join (evidence: `src/localAlert.js`)
- Mac user → Kiosk page and server: dismisses or joins (evidence: `src/localAlert.js`)
- Mac user → macOS dialog: dismisses or joins (evidence: `README.md`)
