# reef-pi/reef-pi architecture

> Architecture diagram of the GitHub repository reef-pi/reef-pi, 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/reef-pi/reef-pi
- Repository: https://github.com/reef-pi/reef-pi

## Overview

reef-pi is a Raspberry Pi reef-tank automation system. A user configures equipment and automation in the browser; the web API exposes controller capabilities, whose subsystems monitor readings, schedule actions, and operate connected devices. The README also documents camera capture, telemetry, alerts, charts, and dashboards. Sampled controllers confirm device, persistence, and statistics interactions; the full API routing and several feature implementations were not sampled, so those links are kept at the documented subsystem level.

Main entry points: [`controller/controller.go`](https://github.com/reef-pi/reef-pi/blob/main/controller/controller.go) (Controller interfaces), [`controller/device_manager/connectors`](https://github.com/reef-pi/reef-pi/tree/main/controller/device_manager/connectors) (I/O connectors), [`controller/storage/boltdb.go`](https://github.com/reef-pi/reef-pi/blob/main/controller/storage/boltdb.go) (Bolt storage), [`controller/telemetry/stats_manager.go`](https://github.com/reef-pi/reef-pi/blob/main/controller/telemetry/stats_manager.go) (Metric history)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web interface"]
  node_ui["Browser UI<br/>[app.jsx]"]
  node_routes["Feature routes"]
  node_dashboard["Dashboard and charts<br/>[main.jsx]"]
end

subgraph group_control["Controller capabilities"]
  node_api["HTTP API<br/>[impl.go]"]
  node_controller["Controller interfaces<br/>[controller.go]"]
  node_equipment["Equipment control<br/>[controller.go]"]
  node_temperature["Temperature control<br/>[controller.go]"]
  node_ph["pH monitoring<br/>[controller.go]"]
  node_ato["Auto top-off<br/>[controller.go]"]
  node_lighting["Lighting automation<br/>[controller.go]"]
  node_doser["Dosing control<br/>[controller.go]"]
  node_timers["Timers and reminders<br/>[controller.go]"]
  node_camera["Camera capture"]
end

subgraph group_devices["Device control"]
  node_connectors["I/O connectors"]
  node_drivers["Hardware drivers"]
  node_device_manager["Device manager<br/>[device_manager.go]"]
end

subgraph group_services["Persistence and telemetry"]
  node_store[("Bolt storage<br/>[boltdb.go]")]
  node_stats["Metric history<br/>[stats_manager.go]"]
  node_telemetry["Telemetry and alerts"]
end

node_user(("Tank operator"))
node_hardware{{"Tank electronics"}}
node_external(("Telemetry services"))

node_user -->|"configures"| node_ui
node_ui -->|"navigates"| node_routes
node_routes -->|"requests"| node_api
node_api -->|"dispatches"| node_controller
node_controller -->|"manages"| node_equipment
node_controller -->|"manages"| node_temperature
node_controller -->|"manages"| node_ph
node_controller -->|"manages"| node_ato
node_controller -->|"manages"| node_lighting
node_controller -->|"manages"| node_doser
node_controller -->|"manages"| node_timers
node_controller -->|"manages"| node_camera
node_equipment -->|"configures outlets"| node_connectors
node_temperature -->|"reads inputs"| node_connectors
node_ph -->|"reads inputs"| node_connectors
node_ato -->|"reads inlets"| node_connectors
node_lighting -->|"controls jacks"| node_connectors
node_doser -->|"controls jacks"| node_connectors
node_device_manager -->|"initializes"| node_drivers
node_device_manager -->|"provisions"| node_connectors
node_connectors -->|"uses"| node_drivers
node_drivers -->|"controls"| node_hardware
node_equipment -->|"persists"| node_store
node_temperature -->|"persists"| node_store
node_ph -->|"persists"| node_store
node_ato -->|"persists"| node_store
node_lighting -->|"persists"| node_store
node_doser -->|"persists"| node_store
node_timers -->|"persists"| node_store
node_temperature -->|"records readings"| node_stats
node_ph -->|"records readings"| node_stats
node_ato -->|"records usage"| node_stats
node_doser -->|"records usage"| node_stats
node_lighting -->|"records usage"| node_stats
node_stats -->|"saves history"| node_store
node_dashboard -->|"renders view"| node_routes
node_telemetry -.->|"publishes metrics"| node_external
node_telemetry -.->|"sends alerts"| node_external
node_camera -.->|"uploads photos"| node_external

click node_ui "https://github.com/reef-pi/reef-pi/blob/main/front-end/src/app.jsx"
click node_routes "https://github.com/reef-pi/reef-pi/blob/main/front-end/src/main_panel_routes.jsx"
click node_api "https://github.com/reef-pi/reef-pi/blob/main/controller/api/impl.go"
click node_controller "https://github.com/reef-pi/reef-pi/blob/main/controller/controller.go"
click node_equipment "https://github.com/reef-pi/reef-pi/blob/main/controller/modules/equipment/controller.go"
click node_temperature "https://github.com/reef-pi/reef-pi/blob/main/controller/modules/temperature/controller.go"
click node_ph "https://github.com/reef-pi/reef-pi/blob/main/controller/modules/ph/controller.go"
click node_ato "https://github.com/reef-pi/reef-pi/blob/main/controller/modules/ato/controller.go"
click node_lighting "https://github.com/reef-pi/reef-pi/blob/main/controller/modules/lighting/controller.go"
click node_doser "https://github.com/reef-pi/reef-pi/blob/main/controller/modules/doser/controller.go"
click node_timers "https://github.com/reef-pi/reef-pi/blob/main/controller/modules/timer/controller.go"
click node_camera "https://github.com/reef-pi/reef-pi/tree/main/controller/modules/camera"
click node_dashboard "https://github.com/reef-pi/reef-pi/blob/main/front-end/src/dashboard/main.jsx"
click node_connectors "https://github.com/reef-pi/reef-pi/tree/main/controller/device_manager/connectors"
click node_drivers "https://github.com/reef-pi/reef-pi/tree/main/controller/device_manager/drivers"
click node_device_manager "https://github.com/reef-pi/reef-pi/blob/main/controller/device_manager/device_manager.go"
click node_store "https://github.com/reef-pi/reef-pi/blob/main/controller/storage/boltdb.go"
click node_stats "https://github.com/reef-pi/reef-pi/blob/main/controller/telemetry/stats_manager.go"
click node_telemetry "https://github.com/reef-pi/reef-pi/tree/main/controller/telemetry"

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_ui,node_routes,node_dashboard toneBlue
class node_api,node_controller,node_equipment,node_temperature,node_ph,node_ato,node_lighting,node_doser,node_timers,node_camera toneAmber
class node_connectors,node_drivers,node_device_manager toneMint
class node_store,node_stats,node_telemetry toneRose
class node_user,node_hardware,node_external toneIndigo
```

## Components

### Web interface

- [Browser UI](https://github.com/reef-pi/reef-pi/blob/main/front-end/src/app.jsx): `front-end/src/app.jsx`
- [Feature routes](https://github.com/reef-pi/reef-pi/blob/main/front-end/src/main_panel_routes.jsx): `front-end/src/main_panel_routes.jsx`
- [Dashboard and charts](https://github.com/reef-pi/reef-pi/blob/main/front-end/src/dashboard/main.jsx): `front-end/src/dashboard/main.jsx`

### Controller capabilities

- [HTTP API](https://github.com/reef-pi/reef-pi/blob/main/controller/api/impl.go): `controller/api/impl.go`
- [Controller interfaces](https://github.com/reef-pi/reef-pi/blob/main/controller/controller.go): `controller/controller.go`
- [Equipment control](https://github.com/reef-pi/reef-pi/blob/main/controller/modules/equipment/controller.go): `controller/modules/equipment/controller.go`
- [Temperature control](https://github.com/reef-pi/reef-pi/blob/main/controller/modules/temperature/controller.go): `controller/modules/temperature/controller.go`
- [pH monitoring](https://github.com/reef-pi/reef-pi/blob/main/controller/modules/ph/controller.go): `controller/modules/ph/controller.go`
- [Auto top-off](https://github.com/reef-pi/reef-pi/blob/main/controller/modules/ato/controller.go): `controller/modules/ato/controller.go`
- [Lighting automation](https://github.com/reef-pi/reef-pi/blob/main/controller/modules/lighting/controller.go): `controller/modules/lighting/controller.go`
- [Dosing control](https://github.com/reef-pi/reef-pi/blob/main/controller/modules/doser/controller.go): `controller/modules/doser/controller.go`
- [Timers and reminders](https://github.com/reef-pi/reef-pi/blob/main/controller/modules/timer/controller.go): `controller/modules/timer/controller.go`
- [Camera capture](https://github.com/reef-pi/reef-pi/tree/main/controller/modules/camera): `controller/modules/camera`

### Device control

- [I/O connectors](https://github.com/reef-pi/reef-pi/tree/main/controller/device_manager/connectors): `controller/device_manager/connectors`
- [Hardware drivers](https://github.com/reef-pi/reef-pi/tree/main/controller/device_manager/drivers): `controller/device_manager/drivers`
- [Device manager](https://github.com/reef-pi/reef-pi/blob/main/controller/device_manager/device_manager.go): `controller/device_manager/device_manager.go`

### Persistence and telemetry

- [Bolt storage](https://github.com/reef-pi/reef-pi/blob/main/controller/storage/boltdb.go): `controller/storage/boltdb.go`
- [Metric history](https://github.com/reef-pi/reef-pi/blob/main/controller/telemetry/stats_manager.go): `controller/telemetry/stats_manager.go`
- [Telemetry and alerts](https://github.com/reef-pi/reef-pi/tree/main/controller/telemetry): `controller/telemetry`

### Other components

- **Tank operator**
- **Tank electronics**
- **Telemetry services**

## Connections

- Tank operator → Browser UI: configures
- Browser UI → Feature routes: navigates
- Feature routes → HTTP API: requests
- HTTP API → Controller interfaces: dispatches
- Controller interfaces → Equipment control: manages
- Controller interfaces → Temperature control: manages
- Controller interfaces → pH monitoring: manages
- Controller interfaces → Auto top-off: manages
- Controller interfaces → Lighting automation: manages
- Controller interfaces → Dosing control: manages
- Controller interfaces → Timers and reminders: manages
- Controller interfaces → Camera capture: manages
- Equipment control → I/O connectors: configures outlets
- Temperature control → I/O connectors: reads inputs
- pH monitoring → I/O connectors: reads inputs
- Auto top-off → I/O connectors: reads inlets
- Lighting automation → I/O connectors: controls jacks
- Dosing control → I/O connectors: controls jacks
- Device manager → Hardware drivers: initializes
- Device manager → I/O connectors: provisions
- I/O connectors → Hardware drivers: uses
- Hardware drivers → Tank electronics: controls
- Equipment control → Bolt storage: persists
- Temperature control → Bolt storage: persists
- pH monitoring → Bolt storage: persists
- Auto top-off → Bolt storage: persists
- Lighting automation → Bolt storage: persists
- Dosing control → Bolt storage: persists
- Timers and reminders → Bolt storage: persists
- Temperature control → Metric history: records readings
- pH monitoring → Metric history: records readings
- Auto top-off → Metric history: records usage
- Dosing control → Metric history: records usage
- Lighting automation → Metric history: records usage
- Metric history → Bolt storage: saves history
- Dashboard and charts → Feature routes: renders view
- Telemetry and alerts → Telemetry services: publishes metrics
- Telemetry and alerts → Telemetry services: sends alerts
- Camera capture → Telemetry services: uploads photos