# pducharme/codex-claude-quota-display architecture

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

- Interactive diagram: https://gitdiagram.com/pducharme/codex-claude-quota-display
- Repository: https://github.com/pducharme/codex-claude-quota-display

## Overview

Quota Display is a macOS quota companion with an optional network API source and ESP32 mini-screen. The main path is provider sessions on the source Mac → quota bridge → Companion or device display. The Designer adds configurable pages, local and connected data, and nearby-flight alerts. Edges are limited to README statements and shown source references/calls; unsampled details are not assumed.

Main entry points: [`bridge/designer.py`](https://github.com/pducharme/codex-claude-quota-display/blob/main/bridge/designer.py) (Designer config), [`firmware/src/main.cpp`](https://github.com/pducharme/codex-claude-quota-display/blob/main/firmware/src/main.cpp) (Device runtime), [`bridge/quota_bridge.py`](https://github.com/pducharme/codex-claude-quota-display/blob/main/bridge/quota_bridge.py) (Quota bridge), [`firmware/include/DesignerRuntime.h`](https://github.com/pducharme/codex-claude-quota-display/blob/main/firmware/include/DesignerRuntime.h) (Page rendering)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mac["Mac Companion"]
  node_companion["Menu companion<br/>[quota_menu.swift]"]
end

subgraph group_bridge["Quota API"]
  node_api["Quota bridge<br/>[quota_bridge.py]"]
end

subgraph group_designer["Page Designer"]
  node_designer_core["Designer config<br/>[designer.py]"]
  node_designer_ui["Designer editor<br/>[app.js]"]
  node_integrations["Connected data"]
  node_local_data["Mac data<br/>[designer_local.py]"]
  node_web_services["Web services"]
end

subgraph group_device["Mini-screen Firmware"]
  node_device_main["Device runtime<br/>[main.cpp]"]
  node_device_config["Configuration checks"]
  node_device_sleep["Sleep schedule<br/>[DisplaySleep.h]"]
  node_designer_runtime["Page rendering<br/>[DesignerRuntime.h]"]
  node_designer_selection["Page rotation"]
  node_designer_sky["Flight rendering<br/>[DesignerSky.h]"]
  node_designer_fonts["Designer fonts<br/>[DesignerFonts.h]"]
  node_sky_fonts["Flight fonts<br/>[DesignerSkyFonts.h]"]
  node_display_driver["LCD driver"]
end

node_user(("Mac user"))
node_codex["Codex app"]
node_claude["Claude Desktop"]
node_clients["Remote clients"]
node_screen["T-Display S3"]
node_flight_feed["Flight data"]

node_user -->|"configures"| node_companion
node_codex -->|"provides session"| node_companion
node_claude -->|"provides session"| node_companion
node_companion -->|"uses local API"| node_api
node_api -->|"serves quotas"| node_clients
node_api -->|"serves quotas"| node_screen
node_user -->|"edits pages"| node_designer_ui
node_designer_core -->|"uses connections"| node_integrations
node_designer_core -->|"uses local data"| node_local_data
node_designer_core -->|"polls services"| node_web_services
node_api -->|"routes Designer"| node_designer_core
node_designer_core -->|"fetches nearby flights"| node_flight_feed
node_device_main -->|"fetches quotas"| node_api
node_device_main -->|"validates settings"| node_device_config
node_device_main -->|"checks sleep"| node_device_sleep
node_device_main -->|"starts Designer"| node_designer_runtime
node_designer_runtime -->|"selects pages"| node_designer_selection
node_designer_runtime -->|"renders flight page"| node_designer_sky
node_designer_runtime -->|"uses fonts"| node_designer_fonts
node_designer_sky -->|"uses fonts"| node_sky_fonts
node_device_main -.->|"drives display"| node_display_driver
node_designer_ui -->|"publishes pages"| node_designer_core
node_designer_core -->|"publishes pages"| node_device_main

click node_companion "https://github.com/pducharme/codex-claude-quota-display/blob/main/bridge/quota_menu.swift"
click node_api "https://github.com/pducharme/codex-claude-quota-display/blob/main/bridge/quota_bridge.py"
click node_designer_core "https://github.com/pducharme/codex-claude-quota-display/blob/main/bridge/designer.py"
click node_designer_ui "https://github.com/pducharme/codex-claude-quota-display/blob/main/bridge/designer/app.js"
click node_integrations "https://github.com/pducharme/codex-claude-quota-display/blob/main/bridge/designer_integrations.py"
click node_local_data "https://github.com/pducharme/codex-claude-quota-display/blob/main/bridge/designer_local.py"
click node_web_services "https://github.com/pducharme/codex-claude-quota-display/blob/main/bridge/designer_services.py"
click node_device_main "https://github.com/pducharme/codex-claude-quota-display/blob/main/firmware/src/main.cpp"
click node_device_config "https://github.com/pducharme/codex-claude-quota-display/blob/main/firmware/src/ConfigurationValidation.h"
click node_device_sleep "https://github.com/pducharme/codex-claude-quota-display/blob/main/firmware/src/DisplaySleep.h"
click node_designer_runtime "https://github.com/pducharme/codex-claude-quota-display/blob/main/firmware/include/DesignerRuntime.h"
click node_designer_selection "https://github.com/pducharme/codex-claude-quota-display/blob/main/firmware/include/DesignerSelection.h"
click node_designer_sky "https://github.com/pducharme/codex-claude-quota-display/blob/main/firmware/include/DesignerSky.h"
click node_designer_fonts "https://github.com/pducharme/codex-claude-quota-display/blob/main/firmware/include/DesignerFonts.h"
click node_sky_fonts "https://github.com/pducharme/codex-claude-quota-display/blob/main/firmware/include/DesignerSkyFonts.h"
click node_display_driver "https://github.com/pducharme/codex-claude-quota-display/blob/main/firmware/lib/Arduino_AXS15231/src/Arduino_AXS15231.cpp"

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_companion,node_user,node_clients toneBlue
class node_api toneAmber
class node_designer_core,node_designer_ui,node_integrations,node_local_data,node_web_services toneMint
class node_device_main,node_device_config,node_device_sleep,node_designer_runtime,node_designer_selection,node_designer_sky,node_designer_fonts,node_sky_fonts,node_display_driver toneRose
class node_codex,node_claude,node_screen,node_flight_feed toneIndigo
```

## Components

### Mac Companion

- [Menu companion](https://github.com/pducharme/codex-claude-quota-display/blob/main/bridge/quota_menu.swift): `bridge/quota_menu.swift`

### Quota API

- [Quota bridge](https://github.com/pducharme/codex-claude-quota-display/blob/main/bridge/quota_bridge.py): `bridge/quota_bridge.py`

### Page Designer

- [Designer config](https://github.com/pducharme/codex-claude-quota-display/blob/main/bridge/designer.py): `bridge/designer.py`
- [Designer editor](https://github.com/pducharme/codex-claude-quota-display/blob/main/bridge/designer/app.js): `bridge/designer/app.js`
- [Connected data](https://github.com/pducharme/codex-claude-quota-display/blob/main/bridge/designer_integrations.py): `bridge/designer_integrations.py`
- [Mac data](https://github.com/pducharme/codex-claude-quota-display/blob/main/bridge/designer_local.py): `bridge/designer_local.py`
- [Web services](https://github.com/pducharme/codex-claude-quota-display/blob/main/bridge/designer_services.py): `bridge/designer_services.py`

### Mini-screen Firmware

- [Device runtime](https://github.com/pducharme/codex-claude-quota-display/blob/main/firmware/src/main.cpp): `firmware/src/main.cpp`
- [Configuration checks](https://github.com/pducharme/codex-claude-quota-display/blob/main/firmware/src/ConfigurationValidation.h): `firmware/src/ConfigurationValidation.h`
- [Sleep schedule](https://github.com/pducharme/codex-claude-quota-display/blob/main/firmware/src/DisplaySleep.h): `firmware/src/DisplaySleep.h`
- [Page rendering](https://github.com/pducharme/codex-claude-quota-display/blob/main/firmware/include/DesignerRuntime.h): `firmware/include/DesignerRuntime.h`
- [Page rotation](https://github.com/pducharme/codex-claude-quota-display/blob/main/firmware/include/DesignerSelection.h): `firmware/include/DesignerSelection.h`
- [Flight rendering](https://github.com/pducharme/codex-claude-quota-display/blob/main/firmware/include/DesignerSky.h): `firmware/include/DesignerSky.h`
- [Designer fonts](https://github.com/pducharme/codex-claude-quota-display/blob/main/firmware/include/DesignerFonts.h): `firmware/include/DesignerFonts.h`
- [Flight fonts](https://github.com/pducharme/codex-claude-quota-display/blob/main/firmware/include/DesignerSkyFonts.h): `firmware/include/DesignerSkyFonts.h`
- [LCD driver](https://github.com/pducharme/codex-claude-quota-display/blob/main/firmware/lib/Arduino_AXS15231/src/Arduino_AXS15231.cpp): `firmware/lib/Arduino_AXS15231/src/Arduino_AXS15231.cpp`

### Other components

- **Mac user**
- **Codex app**
- **Claude Desktop**
- **Remote clients**
- **T-Display S3**
- **Flight data**

## Connections

- Mac user → Menu companion: configures (evidence: `README.md`)
- Codex app → Menu companion: provides session (evidence: `README.md`)
- Claude Desktop → Menu companion: provides session (evidence: `README.md`)
- Menu companion → Quota bridge: uses local API (evidence: `README.md`)
- Quota bridge → Remote clients: serves quotas (evidence: `README.md`)
- Quota bridge → T-Display S3: serves quotas (evidence: `README.md`)
- Mac user → Designer editor: edits pages (evidence: `README.md`)
- Designer config → Connected data: uses connections (evidence: `bridge/designer.py`)
- Designer config → Mac data: uses local data (evidence: `bridge/designer.py`)
- Designer config → Web services: polls services (evidence: `bridge/designer.py`)
- Quota bridge → Designer config: routes Designer (evidence: `bridge/quota_bridge.py`)
- Designer config → Flight data: fetches nearby flights (evidence: `bridge/designer.py`)
- Device runtime → Quota bridge: fetches quotas (evidence: `firmware/src/main.cpp`)
- Device runtime → Configuration checks: validates settings (evidence: `firmware/src/main.cpp`)
- Device runtime → Sleep schedule: checks sleep (evidence: `firmware/src/main.cpp`)
- Device runtime → Page rendering: starts Designer (evidence: `firmware/src/main.cpp`)
- Page rendering → Page rotation: selects pages (evidence: `firmware/include/DesignerRuntime.h`)
- Page rendering → Flight rendering: renders flight page (evidence: `firmware/include/DesignerRuntime.h`)
- Page rendering → Designer fonts: uses fonts (evidence: `firmware/include/DesignerRuntime.h`)
- Flight rendering → Flight fonts: uses fonts (evidence: `firmware/include/DesignerSky.h`)
- Device runtime → LCD driver: drives display
- Designer editor → Designer config: publishes pages (evidence: `README.md`)
- Designer config → Device runtime: publishes pages (evidence: `README.md`)
