# kizniche/mycodo architecture

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

- Interactive diagram: https://gitdiagram.com/kizniche/mycodo
- Repository: https://github.com/kizniche/mycodo

## Overview

##### Project Type and Purpose
- Mycodo is a full-stack environmental regulation system for SBCs (Raspberry Pi). It couples sensor “Inputs,” control “Functions,” and actuator “Outputs” in a daemon process, and exposes a Flask-based Web UI (and REST API) for configuration, visualization, and management. It uses a relational database (via SQLAlchemy/Alembic) for system configuration and a time-series database (InfluxDB) for measurement data.

##### Main Components
a. Hardware Layer (Sensors & Actuators)
- GPIO, I²C, SPI, UART sensors (temperature, humidity, CO₂, etc.)
- Actuators: relays, PWM devices, pumps, LEDs, motors
b. Mycodo Daemon (“mycodo_daemon.py”)
- Loads Controllers: InputController, FunctionController, OutputController, ConditionalController, PIDController, TriggerController, WidgetController
- Interfaces to hardware (mycodo/inputs, mycodo/outputs, mycodo/devices)
- Writes measurement points to InfluxDB (via mycodo/utils/influx.py)
- Reads configuration from SQL database (via SQLAlchemy models, migrations in alembic_db/)
- Executes Functions (control logic), dispatches Actions
- Communicates with Web UI via REST (Flask-RESTX) or Pyro5 for remote module calls
c. Relational Database
- SQLAlchemy ORM models in mycodo/databases/models/
- Alembic migration scripts in alembic_db/
- Stores users, roles, dashboards, inputs/outputs/functions configuration, notes, logs, themes
d. Time-Series Database (InfluxDB)
- Measurements: stored by the daemon for graphing and alerts
- Dockerized InfluxDB container in docker/influxdb/
e. Web Interface (“mycodo_flask”)
- Flask application using Gunicorn (or native Python) behind Nginx (docker/nginx/)
- Static assets, templates, forms, REST API endpoints in mycodo/mycodo_flask/
- Reads configuration from SQL DB, queries InfluxDB for graphs
- Exposes REST API (flask_restx) for external clients
f. Auxiliary Services (Docker Compose)
- Grafana (docker/grafana/) for alternate visualization
- Telegraf (docker/telegraf/) for instrumentation
- Logrotate service, reverse proxy Nginx, environment scripts

##### Relationships and Data Flow
1. Sensors → Daemon InputController → Measurement Data → InfluxDB
2. Daemon FunctionController → Control logic → OutputController → Actuators
3. Daemon ↔ Relational DB (configuration read/write)
4. Web UI ↔ Relational DB (read/write configs, user management)
5. Web UI ↔ InfluxDB (read time-series for dashboards)
6. Web UI ↔ Daemon (REST API for real-time status, remote commands)
7. External Services (Grafana) ↔ InfluxDB for monitoring
8. Nginx routes external HTTP(S) to Web UI / API

##### Architectural Patterns
- Modular plugin architecture for Inputs, Outputs, Functions, Actions, Widgets
- Controller pattern: separate controllers for each subsystem
- Layered architecture: Hardware → Daemon → Storage → Web UI
- Micro-service style in Docker: each service in its own container
- MVC-like in the Web UI: forms and templates separate from routes and models

##### Technologies & Frameworks
- Python 3, Flask, Flask-RESTX, Gunicorn, SQLAlchemy, Alembic, InfluxDB, Pyro5
- Docker, Docker-Compose, Nginx, Telegraf, Grafana
- Frontend: Bootstrap 4, jQuery, gridstack.js, Highcharts

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Hardware Layer
    subgraph "Host Hardware" 
        direction TB
        Sensors["Sensors (GPIO, I2C, SPI, UART)"]:::hardware
        Actuators["Actuators (Relays, PWM, Motors)"]:::hardware
    end

    %% Daemon Process
    subgraph "Mycodo Daemon" 
        direction TB
        Daemon["mycodo_daemon.py & Controllers"]:::daemon
        ABC["abstract_base_controller.py"]:::daemon
        Controllers["controllers/"]:::daemon
        UtilsInflux["utils/influx.py"]:::daemon
    end

    %% Databases
    subgraph "Databases"
        direction TB
        SQLDB(["Relational DB (SQLAlchemy)"]):::db
        Models["databases/models/"]:::db
        Alembic["alembic_db/"]:::db
        TSDB(["Time-Series DB (InfluxDB)"]):::db
    end

    %% Web Interface
    subgraph "Web UI & REST API"
        direction TB
        FlaskApp["app.py"]:::web
        API["api/"]:::web
        Routes["routes_*.py"]:::web
        Forms["forms/"]:::web
        Templates["templates/"]:::web
        Static["static/"]:::web
        UIUtils["utils/"]:::web
        Extensions["extensions.py"]:::web
    end

    %% Docker Compose Services
    subgraph "Docker Compose" 
        direction TB
        InfluxContainer["InfluxDB Container"]:::external
        Grafana["Grafana"]:::external
        Telegraf["Telegraf"]:::external
        NginxProxy["Nginx Reverse Proxy"]:::external
    end

    %% Utility Scripts & Core Utils
    subgraph "Scripts & Core Utils"
        direction TB
        Scripts["scripts/"]:::external
        Install["install/"]:::external
        DockerSetup["docker/setup.sh"]:::external
        CoreUtils["utils/"]:::external
        Config["config.py"]:::external
    end

    %% Connections
    Sensors -->|"measurements"| Daemon
    Daemon -->|"writes points"| TSDB
    Daemon -->|"reads/writes config"| SQLDB
    Daemon -->|"control commands"| Actuators
    FlaskApp -->|"config read/write"| SQLDB
    FlaskApp -->|"query time-series"| TSDB
    FlaskApp -->|"REST API calls"| Daemon
    Grafana -->|"reads time-series"| TSDB
    NginxProxy -->|"routes HTTP/S"| FlaskApp

    %% Group relations
    TSDB --> InfluxContainer
    Grafana --> TSDB
    Telegraf --> TSDB

    %% Click Events
    click Sensors "https://github.com/kizniche/mycodo/tree/master/mycodo/inputs/"
    click Actuators "https://github.com/kizniche/mycodo/tree/master/mycodo/outputs/"
    click Daemon "https://github.com/kizniche/mycodo/blob/master/mycodo/mycodo_daemon.py"
    click ABC "https://github.com/kizniche/mycodo/blob/master/mycodo/abstract_base_controller.py"
    click Controllers "https://github.com/kizniche/mycodo/tree/master/mycodo/controllers/"
    click UtilsInflux "https://github.com/kizniche/mycodo/blob/master/mycodo/utils/influx.py"
    click Models "https://github.com/kizniche/mycodo/tree/master/mycodo/databases/models/"
    click Alembic "https://github.com/kizniche/mycodo/tree/master/alembic_db/"
    click FlaskApp "https://github.com/kizniche/mycodo/blob/master/mycodo/mycodo_flask/app.py"
    click API "https://github.com/kizniche/mycodo/tree/master/mycodo/mycodo_flask/api/"
    click Routes "https://github.com/kizniche/mycodo/blob/master/mycodo/mycodo_flask/routes_input.py"
    click Forms "https://github.com/kizniche/mycodo/tree/master/mycodo/mycodo_flask/forms/"
    click Templates "https://github.com/kizniche/mycodo/tree/master/mycodo/mycodo_flask/templates/"
    click Static "https://github.com/kizniche/mycodo/tree/master/mycodo/mycodo_flask/static/"
    click UIUtils "https://github.com/kizniche/mycodo/tree/master/mycodo/mycodo_flask/utils/"
    click Extensions "https://github.com/kizniche/mycodo/blob/master/mycodo/mycodo_flask/extensions.py"
    click InfluxContainer "https://github.com/kizniche/mycodo/tree/master/docker/influxdb/Dockerfile"
    click Grafana "https://github.com/kizniche/mycodo/blob/master/docker/grafana/env.grafana"
    click Telegraf "https://github.com/kizniche/mycodo/blob/master/docker/telegraf/telegraf.conf"
    click NginxProxy "https://github.com/kizniche/mycodo/blob/master/docker/nginx/nginx.conf"
    click Scripts "https://github.com/kizniche/mycodo/tree/master/mycodo/scripts/"
    click Install "https://github.com/kizniche/mycodo/tree/master/install/"
    click DockerSetup "https://github.com/kizniche/mycodo/blob/master/docker/setup.sh"
    click CoreUtils "https://github.com/kizniche/mycodo/tree/master/mycodo/utils/"
    click Config "https://github.com/kizniche/mycodo/blob/master/mycodo/config.py"

    %% Styles
    classDef hardware fill:#b2fab4,stroke:#2f855a,color:#000
    classDef daemon fill:#a0c4ff,stroke:#4361ee,color:#000
    classDef web fill:#ffba08,stroke:#f77f00,color:#000
    classDef db fill:#f2f2f2,stroke:#333,color:#000
    classDef external fill:#d3d3d3,stroke:#555,color:#000
```
