# protofy-xyz/protofy architecture

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

- Interactive diagram: https://gitdiagram.com/protofy-xyz/protofy
- Repository: https://github.com/protofy-xyz/protofy

## Overview

The Protofy project is a large-scale, monorepo-based platform that automates control over physical devices using an AI “autopilot” loop. Its core purpose is to monitor sensor states, process them with a large language model (LLM), decide on rules, and trigger actuators in smart or industrial IoT devices (including ESP32-powered modules). The repository contains multiple apps (such as adminpanel, next, api, core, launcher, python, etc.) and many packages that segment the business logic (agents, protobase, protodevice, protoflow, protofy, protolib, protonode, protopy, ui, visualui, etc.).

- Frontend / Node-Based UI – For example, the “adminpanel”, “next”, “nextra”, and “visualui” apps offer the user interface (the node/flow-editor and dashboards). These components provide a visual environment where operators can fine-tune system behavior, onboard devices, and configure rules.
- API and Core Services – The “api” and “core” apps, along with packages such as “protolib”, “protobase”, and “protofy” (which include protocol implementations, device management, and automation logic) form the central backend. They manage the continuous decision loop that reads sensor data and interacts with the LLM and external device logic.
- IoT Device Integration – The “protodevice” package (and related scripts, docker files for IoT deployments) provides support for physical devices (ESP32-based systems via ESPHome, etc.). This module encapsulates device drivers, MQTT communication (as seen in multiple device modules and its MQTT files), and the necessary protocols for deploying code to these devices.
- Automation and Rule Processing – Embedded in the system are modules for rule evaluation, context transfer for the LLM, and automation triggers (for instance, through the “protoflow” package and flow/state machine modules in “protolib”, and state machine packages). They represent the “autopilot” decision loop.
- Infrastructure, Containerization, and Deployment – Notice the many Dockerfiles (docker, docker-compose files in apps and packages) and CI/CD configuration files (GitHub workflows) that suggest containerized microservices that can be deployed in different environments.
- Supporting Infrastructure – Additional packages such as “agents”, “config”, “protonode”, and even “protopy” and “ui” show integration layers (protocol adapters, authentication/authorization, cross-service communication, etc.) that support the overall system.

##### Incorporate Architectural Patterns & Technologies
- Message Bus / MQTT Integration – Emphasize the communication channels dedicated to IoT devices (protocols such as MQTT appear in multiple modules).
- Node-Based Visual Interface – Highlight the “protoflow” and “visualui” components that let users visually engineer the automation rules.
- LLM Integration – Represent the AI-assisted decision part of the loop that takes in sensor inputs, contextual data, and outputs actuator instructions.

##### Detailed Elements
- Infrastructure: Separate sections for deployment artifacts (Docker, CI/CD workflows, pm2 monitoring).

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% IoT Device Integration
    subgraph "IoT Device Integration"
        D1["Sensor Data"]:::iot
        DI["Device Integration (protodevice)"]:::iot
    end

    %% API and Core Services
    subgraph "API and Core Services"
        A_API["API Service"]:::backend
        A_Core["Core Service"]:::backend
        PL["Protocols & Device Management (protolib)"]:::backend
        PFY["Automation Logic (protofy)"]:::backend
        PF["Automation/Rule Engine (protoflow)"]:::automation
    end

    %% Frontend / Node-Based UI
    subgraph "Frontend / Node-Based UI"
        AP["Adminpanel UI"]:::frontend
        NX["Next UI"]:::frontend
        NXTA["Nextra UI"]:::frontend
        VUI["Visual UI"]:::frontend
    end

    %% Supporting Infrastructure
    subgraph "Supporting Infrastructure"
        AG["Agents"]:::support
        CFG["Config"]:::support
        PN["Protonode"]:::support
        PPY["Protopy"]:::support
        PUI["UI Support"]:::support
    end

    %% Infrastructure, Containerization & Deployment
    subgraph "Infrastructure, Containerization & Deployment"
        DOCKER["Docker & Docker-Compose"]:::infrastructure
        DAPI["Dockerfile for API"]:::infrastructure
        DCORE["Dockerfile for Core"]:::infrastructure
        DCOMP["Docker Compose"]:::infrastructure
        CICD["CI/CD Workflows"]:::infrastructure
    end

    %% Data/Control Flow Connections
    D1 --> DI
    DI -->|"sensor-data"| A_API

    A_API <-->|"sync"| A_Core
    A_Core -->|"protocols"| PL
    PL -->|"automation-logic"| PFY
    PFY -->|"trigger"| PF
    PF -->|"control-signals"| DI

    %% Frontend interactions with API
    AP --> A_API
    NX --> A_API
    NXTA --> A_API
    VUI --> A_API

    %% Supporting Infrastructure connections
    AG --- A_Core
    CFG --- A_Core
    PN --- A_Core
    PPY --- A_Core
    PUI --- A_Core

    %% Deployment interactions
    DOCKER --> A_API
    DOCKER --> A_Core
    DOCKER --> DI

    DOCKER --> DAPI
    DOCKER --> DCORE
    DOCKER --> DCOMP
    CICD --> DOCKER

    %% Click Events for Frontend / Node-Based UI
    click AP "https://github.com/protofy-xyz/protofy/tree/main/apps/adminpanel"
    click NX "https://github.com/protofy-xyz/protofy/tree/main/apps/next"
    click NXTA "https://github.com/protofy-xyz/protofy/tree/main/apps/nextra"
    click VUI "https://github.com/protofy-xyz/protofy/tree/main/packages/visualui"

    %% Click Events for API and Core Services
    click A_API "https://github.com/protofy-xyz/protofy/tree/main/apps/api"
    click A_Core "https://github.com/protofy-xyz/protofy/tree/main/apps/core"
    click PL "https://github.com/protofy-xyz/protofy/tree/main/packages/protolib"
    click PFY "https://github.com/protofy-xyz/protofy/tree/main/packages/protofy"

    %% Click Event for IoT Device Integration
    click DI "https://github.com/protofy-xyz/protofy/tree/main/packages/protodevice"

    %% Click Event for Automation/Rule Processing
    click PF "https://github.com/protofy-xyz/protofy/tree/main/packages/protoflow"

    %% Click Events for Supporting Infrastructure
    click AG "https://github.com/protofy-xyz/protofy/tree/main/packages/agents"
    click CFG "https://github.com/protofy-xyz/protofy/tree/main/packages/config"
    click PN "https://github.com/protofy-xyz/protofy/tree/main/packages/protonode"
    click PPY "https://github.com/protofy-xyz/protofy/tree/main/packages/protopy"
    click PUI "https://github.com/protofy-xyz/protofy/tree/main/packages/ui"

    %% Click Events for Infrastructure, Containerization & Deployment
    click DOCKER "https://github.com/protofy-xyz/protofy/tree/main/docker"
    click DAPI "https://github.com/protofy-xyz/protofy/tree/main/apps/api/Dockerfile"
    click DCORE "https://github.com/protofy-xyz/protofy/tree/main/apps/core/Dockerfile"
    click DCOMP "https://github.com/protofy-xyz/protofy/blob/main/docker/docker-compose.yml"
    click CICD "https://github.com/protofy-xyz/protofy/tree/main/.github/workflows"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef backend fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef iot fill:#FFA07A,stroke:#000,stroke-width:2px;
    classDef automation fill:#F0E68C,stroke:#000,stroke-width:2px;
    classDef infrastructure fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef support fill:#FFB6C1,stroke:#000,stroke-width:2px;
```
