# xingclover/beekeeper_monitor architecture

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

- Interactive diagram: https://gitdiagram.com/xingclover/beekeeper_monitor
- Repository: https://github.com/xingclover/beekeeper_monitor

## Overview

Beekeeper Monitor ingests simulated hive-sensor readings and external weather and wildfire observations into PostgreSQL, then evaluates sensor, weather, and wildfire rules to create alarm events and notifications. FastAPI serves monitoring and rule-management endpoints; the Streamlit dashboard consumes that API for live and historical views, filtering, and alert inspection. The README also describes dbt analytics and Superset, but those components are absent from the supplied tree, so they are shown as documented external capabilities. Some subsystem links are limited to README statements or source-index references.

Main entry points: [`core/main.py`](https://github.com/xingclover/beekeeper_monitor/blob/main/core/main.py) (Pipeline runner), [`ingestion/weather/pipeline.py`](https://github.com/xingclover/beekeeper_monitor/blob/main/ingestion/weather/pipeline.py) (Weather ingestion), [`ingestion/wildfire/pipeline.py`](https://github.com/xingclover/beekeeper_monitor/blob/main/ingestion/wildfire/pipeline.py) (Wildfire ingestion), [`dashboard/pages`](https://github.com/xingclover/beekeeper_monitor/tree/main/dashboard/pages) (Dashboard pages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Data ingestion"]
  node_sensor_simulator["Sensor simulator"]
  node_weather_pipeline["Weather ingestion<br/>[pipeline.py]"]
  node_wildfire_pipeline["Wildfire ingestion<br/>[pipeline.py]"]
  node_location_repository["Location lookup"]
  node_ingestion_jobs["Job tracking<br/>[jobs.py]"]
end

subgraph group_process["Alerts and notifications"]
  node_pipeline_runner["Pipeline runner<br/>[main.py]"]
  node_sensor_rules["Sensor rule pipeline<br/>[sensor_pipeline.py]"]
  node_weather_rules["Weather rule pipeline"]
  node_wildfire_rules["Wildfire rule pipeline"]
  node_rule_evaluator["Rule evaluator<br/>[evaluator.py]"]
  node_rule_repository["Rule repository<br/>[repository.py]"]
  node_notification_pipeline["Notification processing<br/>[pipeline.py]"]
  node_notification_repository["Notification repository<br/>[repository.py]"]
end

subgraph group_serve["API serving"]
  node_api_app["FastAPI application<br/>[main.py]"]
  node_api_routes["Monitoring and rules API"]
end

subgraph group_dashboard["Monitoring dashboard"]
  node_dashboard_app["Streamlit dashboard<br/>[app.py]"]
  node_dashboard_pages["Dashboard pages"]
  node_dashboard_services["Dashboard services"]
  node_api_client["API client<br/>[api_client.py]"]
  node_filter_helpers["Filter helpers<br/>[filter_utils.py]"]
end

subgraph group_analytics["Analytics"]
  node_dbt["dbt transformations"]
  node_analytics_store[("Analytics marts")]
  node_superset["Superset exploration"]
end

node_operators(("Operators"))
node_external_sources(("Data sources"))
node_postgres[("PostgreSQL")]

node_operators -->|"views"| node_dashboard_app
node_external_sources -->|"provides forecasts"| node_weather_pipeline
node_external_sources -->|"provides detections"| node_wildfire_pipeline
node_sensor_simulator -->|"stores readings"| node_postgres
node_weather_pipeline -->|"stores observations"| node_postgres
node_wildfire_pipeline -->|"stores observations"| node_postgres
node_weather_pipeline -->|"fetches locations"| node_location_repository
node_weather_pipeline -->|"tracks jobs"| node_ingestion_jobs
node_wildfire_pipeline -->|"fetches locations"| node_location_repository
node_wildfire_pipeline -->|"tracks jobs"| node_ingestion_jobs
node_pipeline_runner -->|"runs"| node_sensor_rules
node_pipeline_runner -->|"runs"| node_weather_rules
node_pipeline_runner -->|"runs"| node_wildfire_rules
node_pipeline_runner -->|"runs"| node_notification_pipeline
node_sensor_rules -->|"reads and writes"| node_rule_repository
node_weather_rules -->|"reads and writes"| node_rule_repository
node_wildfire_rules -->|"reads and writes"| node_rule_repository
node_sensor_rules -->|"tests rules"| node_rule_evaluator
node_weather_rules -->|"tests rules"| node_rule_evaluator
node_wildfire_rules -->|"tests rules"| node_rule_evaluator
node_notification_pipeline -->|"creates records"| node_notification_repository
node_api_app -->|"registers routes"| node_api_routes
node_postgres -->|"serves data through"| node_api_app
node_api_app -->|"serves dashboard"| node_dashboard_app
node_dashboard_app -->|"uses"| node_api_client
node_dashboard_pages -->|"requests data"| node_api_client
node_dashboard_services -.->|"fetches API data"| node_api_client
node_dashboard_pages -.->|"uses services"| node_dashboard_services
node_dashboard_pages -.->|"builds filters"| node_filter_helpers
node_postgres -->|"transforms OLTP"| node_dbt
node_dbt -->|"builds marts"| node_analytics_store
node_analytics_store -->|"feeds exploration"| node_superset

click node_sensor_simulator "https://github.com/xingclover/beekeeper_monitor/blob/main/ingestion/sensors/hive_sensor_simulator.py"
click node_weather_pipeline "https://github.com/xingclover/beekeeper_monitor/blob/main/ingestion/weather/pipeline.py"
click node_wildfire_pipeline "https://github.com/xingclover/beekeeper_monitor/blob/main/ingestion/wildfire/pipeline.py"
click node_location_repository "https://github.com/xingclover/beekeeper_monitor/blob/main/ingestion/common/location_repository.py"
click node_ingestion_jobs "https://github.com/xingclover/beekeeper_monitor/blob/main/ingestion/common/jobs.py"
click node_pipeline_runner "https://github.com/xingclover/beekeeper_monitor/blob/main/core/main.py"
click node_sensor_rules "https://github.com/xingclover/beekeeper_monitor/blob/main/rule_engine/pipeline/sensor_pipeline.py"
click node_weather_rules "https://github.com/xingclover/beekeeper_monitor/blob/main/rule_engine/pipeline/weather_pipeline.py"
click node_wildfire_rules "https://github.com/xingclover/beekeeper_monitor/blob/main/rule_engine/pipeline/wildfire_pipeline.py"
click node_rule_evaluator "https://github.com/xingclover/beekeeper_monitor/blob/main/rule_engine/evaluator.py"
click node_rule_repository "https://github.com/xingclover/beekeeper_monitor/blob/main/rule_engine/repository.py"
click node_notification_pipeline "https://github.com/xingclover/beekeeper_monitor/blob/main/notification/pipeline.py"
click node_notification_repository "https://github.com/xingclover/beekeeper_monitor/blob/main/notification/repository.py"
click node_api_app "https://github.com/xingclover/beekeeper_monitor/blob/main/api/main.py"
click node_api_routes "https://github.com/xingclover/beekeeper_monitor/tree/main/api/routers"
click node_dashboard_app "https://github.com/xingclover/beekeeper_monitor/blob/main/dashboard/app.py"
click node_dashboard_pages "https://github.com/xingclover/beekeeper_monitor/tree/main/dashboard/pages"
click node_dashboard_services "https://github.com/xingclover/beekeeper_monitor/tree/main/dashboard/services"
click node_api_client "https://github.com/xingclover/beekeeper_monitor/blob/main/dashboard/utils/api_client.py"
click node_filter_helpers "https://github.com/xingclover/beekeeper_monitor/blob/main/dashboard/utils/filter_utils.py"

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_sensor_simulator,node_weather_pipeline,node_wildfire_pipeline,node_location_repository,node_ingestion_jobs toneBlue
class node_pipeline_runner,node_sensor_rules,node_weather_rules,node_wildfire_rules,node_rule_evaluator,node_rule_repository,node_notification_pipeline,node_notification_repository,node_postgres toneAmber
class node_api_app,node_api_routes toneMint
class node_dashboard_app,node_dashboard_pages,node_dashboard_services,node_api_client,node_filter_helpers toneRose
class node_dbt,node_analytics_store,node_superset,node_operators,node_external_sources toneIndigo
```

## Components

### Data ingestion

- [Sensor simulator](https://github.com/xingclover/beekeeper_monitor/blob/main/ingestion/sensors/hive_sensor_simulator.py): `ingestion/sensors/hive_sensor_simulator.py`
- [Weather ingestion](https://github.com/xingclover/beekeeper_monitor/blob/main/ingestion/weather/pipeline.py): `ingestion/weather/pipeline.py`
- [Wildfire ingestion](https://github.com/xingclover/beekeeper_monitor/blob/main/ingestion/wildfire/pipeline.py): `ingestion/wildfire/pipeline.py`
- [Location lookup](https://github.com/xingclover/beekeeper_monitor/blob/main/ingestion/common/location_repository.py): `ingestion/common/location_repository.py`
- [Job tracking](https://github.com/xingclover/beekeeper_monitor/blob/main/ingestion/common/jobs.py): `ingestion/common/jobs.py`

### Alerts and notifications

- [Pipeline runner](https://github.com/xingclover/beekeeper_monitor/blob/main/core/main.py): `core/main.py`
- [Sensor rule pipeline](https://github.com/xingclover/beekeeper_monitor/blob/main/rule_engine/pipeline/sensor_pipeline.py): `rule_engine/pipeline/sensor_pipeline.py`
- [Weather rule pipeline](https://github.com/xingclover/beekeeper_monitor/blob/main/rule_engine/pipeline/weather_pipeline.py): `rule_engine/pipeline/weather_pipeline.py`
- [Wildfire rule pipeline](https://github.com/xingclover/beekeeper_monitor/blob/main/rule_engine/pipeline/wildfire_pipeline.py): `rule_engine/pipeline/wildfire_pipeline.py`
- [Rule evaluator](https://github.com/xingclover/beekeeper_monitor/blob/main/rule_engine/evaluator.py): `rule_engine/evaluator.py`
- [Rule repository](https://github.com/xingclover/beekeeper_monitor/blob/main/rule_engine/repository.py): `rule_engine/repository.py`
- [Notification processing](https://github.com/xingclover/beekeeper_monitor/blob/main/notification/pipeline.py): `notification/pipeline.py`
- [Notification repository](https://github.com/xingclover/beekeeper_monitor/blob/main/notification/repository.py): `notification/repository.py`

### API serving

- [FastAPI application](https://github.com/xingclover/beekeeper_monitor/blob/main/api/main.py): `api/main.py`
- [Monitoring and rules API](https://github.com/xingclover/beekeeper_monitor/tree/main/api/routers): `api/routers`

### Monitoring dashboard

- [Streamlit dashboard](https://github.com/xingclover/beekeeper_monitor/blob/main/dashboard/app.py): `dashboard/app.py`
- [Dashboard pages](https://github.com/xingclover/beekeeper_monitor/tree/main/dashboard/pages): `dashboard/pages`
- [Dashboard services](https://github.com/xingclover/beekeeper_monitor/tree/main/dashboard/services): `dashboard/services`
- [API client](https://github.com/xingclover/beekeeper_monitor/blob/main/dashboard/utils/api_client.py): `dashboard/utils/api_client.py`
- [Filter helpers](https://github.com/xingclover/beekeeper_monitor/blob/main/dashboard/utils/filter_utils.py): `dashboard/utils/filter_utils.py`

### Analytics

- **dbt transformations**
- **Analytics marts**
- **Superset exploration**

### Other components

- **Operators**
- **Data sources**
- **PostgreSQL**

## Connections

- Operators → Streamlit dashboard: views
- Data sources → Weather ingestion: provides forecasts
- Data sources → Wildfire ingestion: provides detections
- Sensor simulator → PostgreSQL: stores readings
- Weather ingestion → PostgreSQL: stores observations
- Wildfire ingestion → PostgreSQL: stores observations
- Weather ingestion → Location lookup: fetches locations (evidence: `ingestion/weather/pipeline.py`)
- Weather ingestion → Job tracking: tracks jobs (evidence: `ingestion/weather/pipeline.py`)
- Wildfire ingestion → Location lookup: fetches locations (evidence: `ingestion/wildfire/pipeline.py`)
- Wildfire ingestion → Job tracking: tracks jobs (evidence: `ingestion/wildfire/pipeline.py`)
- Pipeline runner → Sensor rule pipeline: runs (evidence: `core/main.py`)
- Pipeline runner → Weather rule pipeline: runs (evidence: `core/main.py`)
- Pipeline runner → Wildfire rule pipeline: runs (evidence: `core/main.py`)
- Pipeline runner → Notification processing: runs (evidence: `core/main.py`)
- Sensor rule pipeline → Rule repository: reads and writes (evidence: `rule_engine/pipeline/sensor_pipeline.py`)
- Weather rule pipeline → Rule repository: reads and writes (evidence: `rule_engine/pipeline/weather_pipeline.py`)
- Wildfire rule pipeline → Rule repository: reads and writes (evidence: `rule_engine/pipeline/wildfire_pipeline.py`)
- Sensor rule pipeline → Rule evaluator: tests rules (evidence: `rule_engine/pipeline/sensor_pipeline.py`)
- Weather rule pipeline → Rule evaluator: tests rules (evidence: `rule_engine/pipeline/weather_pipeline.py`)
- Wildfire rule pipeline → Rule evaluator: tests rules (evidence: `rule_engine/pipeline/wildfire_pipeline.py`)
- Notification processing → Notification repository: creates records (evidence: `notification/pipeline.py`)
- FastAPI application → Monitoring and rules API: registers routes (evidence: `api/main.py`)
- PostgreSQL → FastAPI application: serves data through
- FastAPI application → Streamlit dashboard: serves dashboard
- Streamlit dashboard → API client: uses (evidence: `dashboard/app.py`)
- Dashboard pages → API client: requests data (evidence: `dashboard/pages/4_Alarm&Notifications.py`)
- Dashboard services → API client: fetches API data (evidence: `dashboard/services/overview_service.py`)
- Dashboard pages → Dashboard services: uses services
- Dashboard pages → Filter helpers: builds filters
- PostgreSQL → dbt transformations: transforms OLTP
- dbt transformations → Analytics marts: builds marts
- Analytics marts → Superset exploration: feeds exploration
