# sepse/prishtina-open-brewery architecture

> Architecture diagram of the GitHub repository sepse/prishtina-open-brewery, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sepse/prishtina-open-brewery
- Repository: https://github.com/sepse/prishtina-open-brewery

## Overview

##### Project Type and Purpose
- This is a research-oriented, open-source hardware+software system (“Open Source Brewery”) for precision beer brewing.
- It combines:
- Embedded firmware on microcontrollers (ESP8266/ESP32/Arduino)
- Edge computing & data aggregation (Raspberry Pi + Python)
- Machine-learning recipe generation and analytics
- Web-based dashboards and user interfaces
- A public GitHub portal for code, hardware schematics, and datasets

##### Sketch the High-Level Architectural Layers
a. Hardware Layer
b. Firmware & Edge Layer
c. Data & Compute Layer
d. ML & Analytics Layer
e. Presentation & Integration Layer
f. Collaboration & External Services

##### Main Components & Their Roles
- Sensors (Temp, Humidity, CO₂, Flow)
– Physically attached to mash tuns, fermenters, and dispensing lines.
- Microcontrollers (ESP32/ESP8266/Arduino)
– Read sensor data.
– Control actuators (heaters, pumps, RFID locks).
– Publish data via MQTT/HTTP to the aggregator.
- Raspberry Pi (Edge Aggregator)
– Subscribes to sensor streams (MQTT broker or HTTP endpoints).
– Runs Python scripts to log data locally and forward to central DB.
– Hosts a local web dashboard (Flask/NodeJS).
- Central Database
– Time-series store (e.g., InfluxDB, TimescaleDB) for sensor logs.
– Relational or document store (e.g., PostgreSQL, MongoDB) for recipes and metadata.
- Machine-Learning / LLM Engine
– Batch jobs or microservice for recipe suggestion (e.g., Python + PyTorch).
– Data pipeline reads historical logs, trains/predicts, writes back recommendations.
– Optional REST/gRPC interface for on-demand queries.
- Web Dashboard & APIs
– Frontend (React/Vue) visualizing real-time data and ML suggestions.
– Backend API (FastAPI/Express) serving data from DB and ML engine.
- Open Resources Portal (GitHub)
– Source code (firmware/, backend/, ml/, docs/)
– Hardware schematics & BOMs
– Public datasets and community recipe contributions

##### Relationships and Data Flows
1. Sensors → Microcontrollers (analog/digital signals)
2. Microcontrollers → Edge Aggregator (MQTT/HTTP)
3. Edge Aggregator → Central Database (write data)
4. Central Database → Dashboards & Analytics (read data)
5. Central Database → ML Engine (training data)
6. ML Engine → Central Database (model outputs)
7. ML Engine → Frontend/API (recommendations)
8. User → Frontend/API (queries, recipe requests)
9. Contributors ↔ GitHub portal (code, data, docs)

##### Architectural Patterns
- Modular layers: hardware → firmware → edge → cloud → UI.
- Publish/subscribe (MQTT) between devices and aggregator.
- Microservices or functions for ML tasks.
- Time-series vs. relational DB separation.
- Community contributions via GitOps on GitHub.

##### Capturing Essential Details
- Raspberry Pi running both logging and local dashboard services.
- Distinguish time-series DB vs. relational DB for recipes.
- ML/LLM pipelines separately from real-time monitoring.
- User feedback loops (brewer queries ML, community submits recipes).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Hardware Layer
    subgraph "Hardware Layer"
        direction TB
        Sensors["Sensors\n(Temp, Humidity, CO₂, Flow)"]:::hardware
        MC["Microcontrollers\n(ESP32/ESP8266/Arduino)"]:::hardware
    end

    %% Firmware & Edge Layer
    subgraph "Firmware & Edge Layer"
        direction TB
        Pi["Raspberry Pi\n(Edge Aggregator)"]:::firmware
    end

    %% Data & Compute Layer
    subgraph "Data & Compute Layer"
        direction TB
        TSDB["Time-Series DB\n(InfluxDB/TimescaleDB)"]:::data
        RDB["Relational DB\n(PostgreSQL/MongoDB)"]:::data
    end

    %% ML & Analytics Layer
    subgraph "ML & Analytics Layer"
        direction TB
        ML["ML/LLM Engine\n(Python/PyTorch)"]:::ml
    end

    %% Presentation & Integration Layer
    subgraph "Presentation & Integration Layer"
        direction TB
        FE["Web Frontend\n(React/Vue)"]:::ui
        BE["Backend API\n(FastAPI/Express)"]:::ui
    end

    %% Collaboration & External Services
    subgraph "Collaboration & External Services"
        direction TB
        GitHub["Open Resources Portal\n(GitHub)"]:::external
        Contrib["Contributors"]:::external
        User["User\n(Brewer)"]:::external
    end

    %% Connections
    Sensors -->|"analog/digital signals"| MC
    MC -->|"MQTT Publish/HTTP POST"| Pi
    Pi -->|"Write Data (TLS)"| TSDB
    Pi -->|"Write Data (TLS)"| RDB
    TSDB -->|"Read Data"| BE
    RDB -->|"Read Metadata"| BE
    TSDB -->|"Training Data"| ML
    ML -->|"Model Outputs"| TSDB
    ML -->|"Recommendations (REST/gRPC)"| BE
    BE -->|"Serve Data"| FE
    User -->|"Queries/Requests"| FE
    FE -->|"API Calls"| BE
    Contrib <-->|"Git/GitOps"| GitHub

    %% Click Events
    click GitHub "https://github.com/sepse/prishtina-open-brewery/blob/main/README.md"

    %% Styles
    classDef hardware fill:#e0ffe0,stroke:#006400,color:#006400
    classDef firmware fill:#ffe0b2,stroke:#ff8c00,color:#ff8c00
    classDef data fill:#e0f0ff,stroke:#0066cc,color:#0066cc
    classDef ml fill:#f3e0ff,stroke:#800080,color:#800080
    classDef ui fill:#e0fffa,stroke:#008080,color:#008080
    classDef external fill:#f0f0f0,stroke:#808080,color:#404040
```
