# cambiegroup/flowchem architecture

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

- Interactive diagram: https://gitdiagram.com/cambiegroup/flowchem
- Repository: https://github.com/cambiegroup/flowchem

## Overview

##### Main Components
- Core Application: At the center is the main Flowchem application (located in the src/flowchem folder) that handles orchestration.
- Configuration Module: The configuration parser (see src/flowchem/server/configuration_parser.py) reads the configuration file with device connection details.
- Device Drivers & Components: The devices are modularized into drivers – look into folders like src/flowchem/devices, src/flowchem/components, and their subdirectories for specific device implementations (e.g., pumps, valves, sensors). These driver modules abstract the details of communication with each instrument.
- Communication & API Layer: The server components, especially in src/flowchem/server, include FastAPI-based endpoints (e.g., src/flowchem/server/fastapi_server.py) and other communication pathways (like zeroconf in src/flowchem/server/zeroconf_server.py) to expose device capabilities via a web interface.
- Client Interfaces: There are client modules (found under src/flowchem/client) that provide Python and possibly other language integrations, making the system accessible to both a web browser and programmatic clients.

##### Relationships and Data Flow
- Device Manager/Connection Layer: From the core application, indicate connections to multiple “Device Driver” modules. Each driver (or group of drivers, such as pumps, valves, sensors, etc.) represents the abstraction layer for a specific type of device.
- API / Server Layer: Link the Core Application to the “API Server” (FastAPI, Zeroconf Server) that handles HTTP requests, thereby exposing endpoints to control devices.

##### Architectural Patterns and Design Principles
- Modular Design: Emphasize that each device type is implemented as a separate module (see the various directories under src/flowchem/devices and src/flowchem/components). This supports extensibility as new device types can be plugged in.
- Separation of Concerns: Clearly delineate configuration management, device abstraction, API routing, and client communication.
- Single Unified API: Stress that regardless of underlying protocols or command syntax of each device, Flowchem provides a consistent API layer.

##### Technologies and Frameworks
- Python 3.10+ as the programming language.
- FastAPI for building the server web API (including asynchronous client support as seen in src/flowchem/client/async_client.py).
- GitHub Actions for CI/CD (workflows are in .github/workflows).

##### Final Touches
- Clarity and detail – do not shy away from dividing the core application into as many components as needed to capture the essential architectural elements.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Entities
    U("User/Admin"):::external
    CF("Configuration File (TOML)"):::external
    ED("Physical Instruments (Pumps,Valves,Sensors)"):::external

    %% Backend & Control Layer
    subgraph "Backend & Control Layer"
        CP("Core Application"):::core
        CC("Configuration Parser"):::config
        DR("Device Manager/Drivers"):::drivers
        %% API Servers Subgraph
        subgraph "API Servers"
            FS("FastAPI Server"):::api
            ZS("Zeroconf Server"):::api
        end
    end

    %% Device Drivers & Components
    subgraph "Device Drivers & Components"
        DDRV("Device Drivers"):::drivers
        COMP("Component Abstraction"):::drivers
        PLUG("Plugin Support"):::drivers
    end

    %% Client Interfaces Layer
    subgraph "Client Interfaces"
        CLI("Client Libraries & Web Clients"):::client
    end

    %% Data Flow Connections
    U -->|"starts"| CF
    CF -->|"reads-config"| CC
    CC -->|"initializes"| CP
    CP -->|"manages"| DR
    CP -->|"exposes"| FS
    CP -->|"exposes"| ZS
    CLI -->|"invokes"| FS
    CLI -->|"invokes"| ZS
    FS -->|"sends-cmds"| DR
    ZS -->|"sends-cmds"| DR
    DR -->|"communicates"| ED
    FS -->|"returns-status"| CLI
    ZS -->|"returns-status"| CLI
    ED -->|"sends-data"| FS
    ED -->|"sends-data"| ZS

    %% Breakdown of Device Drivers into Detailed Modules
    DR --> DDRV
    DR --> COMP
    DR --> PLUG

    %% Click Events for Component Mapping
    click CP "https://github.com/cambiegroup/flowchem/tree/main/src/flowchem"
    click CC "https://github.com/cambiegroup/flowchem/blob/main/src/flowchem/server/configuration_parser.py"
    click DDRV "https://github.com/cambiegroup/flowchem/tree/main/src/flowchem/devices"
    click COMP "https://github.com/cambiegroup/flowchem/tree/main/src/flowchem/components"
    click FS "https://github.com/cambiegroup/flowchem/blob/main/src/flowchem/server/fastapi_server.py"
    click ZS "https://github.com/cambiegroup/flowchem/blob/main/src/flowchem/server/zeroconf_server.py"
    click CLI "https://github.com/cambiegroup/flowchem/tree/main/src/flowchem/client"
    click PLUG "https://github.com/cambiegroup/flowchem/blob/main/src/flowchem/devices/known_plugins.py"

    %% Styles
    classDef core fill:#cff,stroke:#036,stroke-width:2px
    classDef config fill:#cfc,stroke:#060,stroke-width:2px
    classDef drivers fill:#fcf,stroke:#906,stroke-width:2px
    classDef api fill:#ffc,stroke:#993,stroke-width:2px
    classDef client fill:#def,stroke:#369,stroke-width:2px
    classDef external fill:#eee,stroke:#888,stroke-width:2px
```
