# griffxen/ambient_dashboard architecture

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

- Interactive diagram: https://gitdiagram.com/griffxen/ambient_dashboard
- Repository: https://github.com/griffxen/ambient_dashboard

## Overview

Ambient Dashboard is an Electron app for a portrait secondary display, with a local control panel and APIs. Its main workflow is: the desktop process fetches agenda and system data, serves the dashboard, and the renderer presents a time-aware schedule, weather, and status; users manage settings and memos from the control panel. Local integrations also expose LAN memo editing and temporary presence notifications. The excerpts show key process and service relationships; some renderer-to-main IPC and presence dispatch details are not shown, so those links are omitted or marked unverified.

Main entry points: [`electron/main.cjs`](https://github.com/griffxen/ambient_dashboard/blob/main/electron/main.cjs) (Desktop coordinator), [`electron/services.cjs`](https://github.com/griffxen/ambient_dashboard/blob/main/electron/services.cjs) (System data services), [`src/main.tsx`](https://github.com/griffxen/ambient_dashboard/blob/main/src/main.tsx) (Dashboard renderer), [`src/control.tsx`](https://github.com/griffxen/ambient_dashboard/blob/main/src/control.tsx) (Control panel)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Desktop runtime"]
  node_electron["Desktop coordinator<br/>[main.cjs]"]
  node_display_window["Display window<br/>[main.cjs]"]
end

subgraph group_display["Dashboard display"]
  node_dashboard["Dashboard renderer<br/>[main.tsx]"]
  node_appearance["Appearance rules<br/>[appearance.ts]"]
  node_control_ui["Control panel<br/>[control.tsx]"]
end

subgraph group_services["Data services"]
  node_services["System data services<br/>[services.cjs]"]
  node_weather_events["Weather event rules<br/>[weather-events.cjs]"]
  node_media_reader["Linux media reader<br/>[linux-media.py]"]
  node_agenda["Agenda retrieval<br/>[main.cjs]"]
  node_memo_store[("Memo persistence<br/>[main.cjs]")]
end

subgraph group_interfaces["Local interfaces"]
  node_control_server["Local control API<br/>[control-server.cjs]"]
  node_lan_memo["LAN memo editor<br/>[lan-memo.cjs]"]
  node_presence_api["Presence API<br/>[control-server.cjs]"]
end

node_user(("Dashboard user"))
node_external_app(("Local app"))
node_planner{{"Planner service"}}
node_weather_provider{{"Weather provider"}}
node_media_session{{"OS media session"}}

node_user -->|"views"| node_display_window
node_electron -->|"calls"| node_services
node_electron -->|"opens"| node_display_window
node_display_window -->|"loads"| node_dashboard
node_dashboard -->|"renders"| node_control_ui
node_dashboard -->|"uses"| node_appearance
node_control_ui -->|"requests"| node_control_server
node_control_server -->|"dispatches"| node_electron
node_electron -->|"handles"| node_agenda
node_agenda -->|"fetches agenda"| node_planner
node_electron -->|"reads and writes"| node_memo_store
node_electron -->|"starts"| node_lan_memo
node_lan_memo -->|"reads and saves"| node_memo_store
node_services -->|"uses"| node_weather_events
node_services -->|"fetches weather"| node_weather_provider
node_services -.->|"runs on Linux"| node_media_reader
node_media_reader -->|"reads session"| node_media_session
node_external_app -->|"posts presence"| node_presence_api
node_presence_api -.->|"dispatches presence"| node_electron

click node_electron "https://github.com/griffxen/ambient_dashboard/blob/main/electron/main.cjs"
click node_display_window "https://github.com/griffxen/ambient_dashboard/blob/main/electron/main.cjs"
click node_dashboard "https://github.com/griffxen/ambient_dashboard/blob/main/src/main.tsx"
click node_appearance "https://github.com/griffxen/ambient_dashboard/blob/main/src/appearance.ts"
click node_control_ui "https://github.com/griffxen/ambient_dashboard/blob/main/src/control.tsx"
click node_services "https://github.com/griffxen/ambient_dashboard/blob/main/electron/services.cjs"
click node_weather_events "https://github.com/griffxen/ambient_dashboard/blob/main/electron/weather-events.cjs"
click node_media_reader "https://github.com/griffxen/ambient_dashboard/blob/main/electron/linux-media.py"
click node_agenda "https://github.com/griffxen/ambient_dashboard/blob/main/electron/main.cjs"
click node_memo_store "https://github.com/griffxen/ambient_dashboard/blob/main/electron/main.cjs"
click node_control_server "https://github.com/griffxen/ambient_dashboard/blob/main/electron/control-server.cjs"
click node_lan_memo "https://github.com/griffxen/ambient_dashboard/blob/main/electron/lan-memo.cjs"
click node_presence_api "https://github.com/griffxen/ambient_dashboard/blob/main/electron/control-server.cjs"

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_electron,node_display_window,node_user toneBlue
class node_dashboard,node_appearance,node_control_ui toneAmber
class node_services,node_weather_events,node_media_reader,node_agenda,node_memo_store toneMint
class node_control_server,node_lan_memo,node_presence_api toneRose
class node_external_app,node_planner,node_weather_provider,node_media_session toneIndigo
```

## Components

### Desktop runtime

- [Desktop coordinator](https://github.com/griffxen/ambient_dashboard/blob/main/electron/main.cjs): `electron/main.cjs`
- [Display window](https://github.com/griffxen/ambient_dashboard/blob/main/electron/main.cjs): `electron/main.cjs`

### Dashboard display

- [Dashboard renderer](https://github.com/griffxen/ambient_dashboard/blob/main/src/main.tsx): `src/main.tsx`
- [Appearance rules](https://github.com/griffxen/ambient_dashboard/blob/main/src/appearance.ts): `src/appearance.ts`
- [Control panel](https://github.com/griffxen/ambient_dashboard/blob/main/src/control.tsx): `src/control.tsx`

### Data services

- [System data services](https://github.com/griffxen/ambient_dashboard/blob/main/electron/services.cjs): `electron/services.cjs`
- [Weather event rules](https://github.com/griffxen/ambient_dashboard/blob/main/electron/weather-events.cjs): `electron/weather-events.cjs`
- [Linux media reader](https://github.com/griffxen/ambient_dashboard/blob/main/electron/linux-media.py): `electron/linux-media.py`
- [Agenda retrieval](https://github.com/griffxen/ambient_dashboard/blob/main/electron/main.cjs): `electron/main.cjs`
- [Memo persistence](https://github.com/griffxen/ambient_dashboard/blob/main/electron/main.cjs): `electron/main.cjs`

### Local interfaces

- [Local control API](https://github.com/griffxen/ambient_dashboard/blob/main/electron/control-server.cjs): `electron/control-server.cjs`
- [LAN memo editor](https://github.com/griffxen/ambient_dashboard/blob/main/electron/lan-memo.cjs): `electron/lan-memo.cjs`
- [Presence API](https://github.com/griffxen/ambient_dashboard/blob/main/electron/control-server.cjs): `electron/control-server.cjs`

### Other components

- **Dashboard user**
- **Local app**
- **Planner service**
- **Weather provider**
- **OS media session**

## Connections

- Dashboard user → Display window: views (evidence: `README.md`)
- Desktop coordinator → System data services: calls (evidence: `electron/main.cjs`)
- Desktop coordinator → Display window: opens (evidence: `electron/main.cjs`)
- Display window → Dashboard renderer: loads (evidence: `electron/main.cjs`)
- Dashboard renderer → Control panel: renders (evidence: `src/main.tsx`)
- Dashboard renderer → Appearance rules: uses (evidence: `src/main.tsx`)
- Control panel → Local control API: requests (evidence: `README.md`)
- Local control API → Desktop coordinator: dispatches (evidence: `electron/main.cjs`)
- Desktop coordinator → Agenda retrieval: handles (evidence: `electron/main.cjs`)
- Agenda retrieval → Planner service: fetches agenda (evidence: `electron/main.cjs`)
- Desktop coordinator → Memo persistence: reads and writes (evidence: `electron/main.cjs`)
- Desktop coordinator → LAN memo editor: starts (evidence: `electron/main.cjs`)
- LAN memo editor → Memo persistence: reads and saves (evidence: `electron/main.cjs`)
- System data services → Weather event rules: uses (evidence: `electron/services.cjs`)
- System data services → Weather provider: fetches weather (evidence: `README.md`)
- System data services → Linux media reader: runs on Linux
- Linux media reader → OS media session: reads session (evidence: `electron/linux-media.py`)
- Local app → Presence API: posts presence (evidence: `README.md`)
- Presence API → Desktop coordinator: dispatches presence (evidence: `electron/main.cjs`)