# fdewasmes/brewblox-brewfather-service architecture

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

- Interactive diagram: https://gitdiagram.com/fdewasmes/brewblox-brewfather-service
- Repository: https://github.com/fdewasmes/brewblox-brewfather-service

## Overview

##### Main components of the system
- Core Service: The Python service is in the “brewblox_brewfather_service” folder. Within it, the main entry point (__main__.py) kicks off the service, which coordinates brewing automation.
- API Layer: The “api” directory (with brewfather_api_client.py) abstracts and handles interactions with Brewfather’s API, e.g., fetching recipes and batch information.
- Automation Logic: The brewfather_automation.py module contains the core logic to drive the mash automation—moving between steps, handling timers, and checking the Brewtracker state.
- Data Management: The datastore.py module likely persists state or configuration, while schemas.py defines the data contracts.
- External Integrations:
- Brewfather: The external service providing recipes and Brewtracker state. Communication here occurs via HTTP using the Brewfather API client.
- Brewblox: Although not directly part of this codebase, the service is designed to integrate with Brewblox (via Docker configuration and API endpoints) and communicates with it by publishing state events.
- MQTT Broker: The service publishes automation state events on the “brewcast/state/brewfather” topic. This is key for notifying connected clients about progress.
- Deployment Environment: The Docker folder (Dockerfile, before_build.sh) and configuration files (poetry.toml, pyproject.toml, azure-pipelines.yml) indicate containerized deployment and automated CI/CD pipelines.

##### Relationships and interactions
- The Core Service receives API requests (e.g., via the swagger UI endpoint at /brewfather/api/doc) and subsequently invokes the Brewfather API client to load recipes or batch details.
- Once a batch is transitioned to the brewing state, the automation logic takes over: it processes the Brewtracker object, handles “pauseBefore” directives, and advances the mash automation either automatically or in response to manual triggers (via the /proceed endpoint).
- As each step is processed, the service publishes MQTT state events. These events notify Brewblox and any other subscribers of the new automation state (mash, rest, heat, etc.).
- The datastore and schemas ensure that the state, configuration, and temporal data (like timers) are managed consistently.

##### Architectural patterns and design principles
- Layered Architecture: Separate modules handling API interfacing, automation control, and data persistence.
- External Service Integration: Clear boundaries exist between handling Brewfather API calls and internal automation logic.
- Event-Driven Communication: Use of MQTT for broadcasting state changes indicates a reactive design.
- Configuration & Containerization: Environment variables (.env), Docker configuration, and CI/CD pipeline definitions show the project is designed for flexible deployment and integration.

- Labeled Components:
- “Mash Automation Engine” for brewfather_automation.py as the core logic controller.
- “Datastore & Schemas” for managing persistent and structured data.
- “MQTT Broker” that receives state events, labeled with the topic “brewcast/state/brewfather”.
- “External Brewfather Service” (depicted as an external system) which the client communicates with.
- “Brewblox Integration” as the endpoint via which automation progress is consumed.
- From Brewblox UI (or Swagger API client) to the Core Service.
- From the Core Service to Brewfather (using the API Client).
- From the Core Service to the MQTT Broker, indicating event publications.
- Internal modules with standard rectangles.

##### Overall, be as detailed as possible
- Relationships (e.g., API requests from the Swagger UI trigger Brewfather API client calls, results feed into the automation engine that then publishes MQTT events).
- To note the integration between the Dockerized service environment and the external systems (Brewfather, Brewblox, MQTT).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    subgraph "External Systems"
        E1["Brewblox UI/Swagger API"]:::external
        E2["External Brewfather Service"]:::external
        E3["Brewblox Integration"]:::external
    end

    %% Core Service Architecture
    subgraph "Core Service Architecture"
        C1["Core Service"]:::internal
        subgraph "API Layer"
            C2["Brewfather API Client"]:::internal
        end
        C3["Mash Automation Engine"]:::internal
        subgraph "Data Management"
            C4["Datastore"]:::datastore
            C5["Schemas"]:::datastore
        end
        C6["MQTT Broker<br/>(brewcast/state/brewfather)"]:::internal
    end

    %% Deployment Environment
    subgraph "Deployment Environment"
        D1["Dockerfile"]:::deploy
        D2["before_build.sh"]:::deploy
        D3["azure-pipelines.yml"]:::deploy
        D4["poetry.toml"]:::deploy
        D5["pyproject.toml"]:::deploy
    end

    %% External interactions
    E1 -->|"API_request"| C1
    C1 -->|"FetchRecipes"| C2
    C1 -->|"TriggerAutomation"| C3
    C2 -->|"HTTP_Call"| E2
    C3 -->|"UpdateState"| C4
    C3 -->|"UpdateState"| C5
    C3 -->|"PublishState"| C6
    C6 -->|"StateEvents"| E3
    D1 -->|"Deploy"| C1

    %% Styles
    classDef external fill:#F9E79F,stroke:#000,stroke-width:1px;
    classDef internal fill:#AED6F1,stroke:#000,stroke-width:1px;
    classDef datastore fill:#D5F5E3,stroke:#000,stroke-width:1px;
    classDef deploy fill:#FADBD8,stroke:#000,stroke-width:1px;

    %% Click Events
    click C1 "https://github.com/fdewasmes/brewblox-brewfather-service/blob/develop/brewblox_brewfather_service/__main__.py"
    click C2 "https://github.com/fdewasmes/brewblox-brewfather-service/blob/develop/brewblox_brewfather_service/api/brewfather_api_client.py"
    click C3 "https://github.com/fdewasmes/brewblox-brewfather-service/blob/develop/brewblox_brewfather_service/brewfather_automation.py"
    click C4 "https://github.com/fdewasmes/brewblox-brewfather-service/blob/develop/brewblox_brewfather_service/datastore.py"
    click C5 "https://github.com/fdewasmes/brewblox-brewfather-service/blob/develop/brewblox_brewfather_service/schemas.py"
    click D1 "https://github.com/fdewasmes/brewblox-brewfather-service/tree/develop/docker/Dockerfile"
    click D2 "https://github.com/fdewasmes/brewblox-brewfather-service/blob/develop/docker/before_build.sh"
    click D3 "https://github.com/fdewasmes/brewblox-brewfather-service/blob/develop/azure-pipelines.yml"
    click D4 "https://github.com/fdewasmes/brewblox-brewfather-service/blob/develop/poetry.toml"
    click D5 "https://github.com/fdewasmes/brewblox-brewfather-service/blob/develop/pyproject.toml"
```
