# automatedchemistry/flowchem architecture

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

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

## Overview

##### Project Type and Purpose
- flowchem is a Python-based control application for chemistry lab instruments. It combines a command-line interface (CLI), a configuration parser, a FastAPI-powered HTTP server, device-abstraction libraries, and client libraries, exposing heterogeneous hardware under a unified REST/WebSocket API and web UI.

##### File Structure Analysis
- Top level:
- pyproject.toml, README, LICENSE – project metadata and docs
- src/flowchem/ – main code, subdivided into:
– __main__.py – CLI entrypoint
– client/ – Python API clients (sync+async)
– server/ – REST server, core orchestrator, configuration parser, zeroconf
– components/ – high-level “flowchem_component” abstractions (pumps, valves, sensors, analytics)
– devices/ – low-level concrete device drivers and device_finder logic
– utils/ – shared utilities (exceptions, device_finder, people)
– vendor/ – vendored code
- examples/ – usage examples orchestrating experiments via client or config
- tests/ – unit/integration tests per subsystem
- README and docs describe a three-step startup: read config → initialize/start server & devices → expose API/UI.

##### Essential Details to Capture
- The plugin discovery process (device_finder → known_plugins)
- The two server modes: FastAPI vs Zeroconf
- The two client interfaces: sync_client and async_client
- The fact that fast startup goes through configuration_parser → core.init → device instantiation → API ready

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Layer
    User["User"] 
    User -->|uses| CLI

    %% Control Plane
    CLI["CLI & Entrypoint"]:::control
    click CLI "https://github.com/automatedchemistry/flowchem/blob/main/src/flowchem/__main__.py"
    CLI -->|reads config| ConfigParser
    ConfigParser["Configuration Parser"]:::control
    click ConfigParser "https://github.com/automatedchemistry/flowchem/blob/main/src/flowchem/server/configuration_parser.py"
    ConfigParser -->|loads device defs| ServerCore

    %% Configuration File
    ConfigFile(("Configuration File (TOML)")):::config
    click ConfigFile "https://github.com/automatedchemistry/flowchem/blob/main/tests/test_config.toml"
    ConfigParser -->|parses| ConfigFile

    %% Core & Services
    ServerCore["Server Core & Orchestrator"]:::control
    click ServerCore "https://github.com/automatedchemistry/flowchem/blob/main/src/flowchem/server/core.py"
    ServerCore -->|initializes| FastAPI
    ServerCore -->|starts| Zeroconf

    FastAPI["FastAPI Server\n(REST + Web UI)"]:::api
    click FastAPI "https://github.com/automatedchemistry/flowchem/blob/main/src/flowchem/server/fastapi_server.py"
    FastAPI <-->|HTTP/WebSocket| Browser

    Zeroconf["Zeroconf Discovery Service"]:::api
    click Zeroconf "https://github.com/automatedchemistry/flowchem/blob/main/src/flowchem/server/zeroconf_server.py"

    Browser["Web Browser UI"]:::api

    %% Client Libraries
    subgraph "Python Client Library" 
        SyncClient["Sync Client"]:::api
        click SyncClient "https://github.com/automatedchemistry/flowchem/blob/main/src/flowchem/client/client.py"
        AsyncClient["Async Client"]:::api
        click AsyncClient "https://github.com/automatedchemistry/flowchem/blob/main/src/flowchem/client/async_client.py"
    end
    SyncClient <-->|HTTP calls| FastAPI
    AsyncClient <-->|async HTTP| FastAPI

    %% Hardware Abstraction Layers
    subgraph "Device Finder & Plugin Loader"
        DeviceFinder["Device Finder"]:::hardware
        click DeviceFinder "https://github.com/automatedchemistry/flowchem/blob/main/src/flowchem/utils/device_finder.py"
        KnownPlugins["Known Plugins"]:::hardware
        click KnownPlugins "https://github.com/automatedchemistry/flowchem/blob/main/src/flowchem/devices/known_plugins.py"
    end
    ServerCore -->|discovers drivers| DeviceFinder
    DeviceFinder --> KnownPlugins

    DeviceAbstraction["Device-Abstraction Layer\n(flowchem_component)"]:::hardware
    click DeviceAbstraction "https://github.com/automatedchemistry/flowchem/blob/main/src/flowchem/components/flowchem_component.py"
    click DeviceAbstraction "https://github.com/automatedchemistry/flowchem/tree/main/src/flowchem/components/"
    KnownPlugins -->|loads abstractions| DeviceAbstraction

    DeviceDrivers["Device Driver Layer"]:::hardware
    click DeviceDrivers "https://github.com/automatedchemistry/flowchem/tree/main/src/flowchem/devices/"
    DeviceAbstraction -->|delegates to| DeviceDrivers

    Hardware["External Hardware Devices"]:::hardware
    DeviceDrivers -->|serial/TCP/USB| Hardware

    %% Legend
    subgraph Legend
        Ctl["Control Plane"]:::control
        Api["API Layer"]:::api
        Hw["Hardware Layer"]:::hardware
        Cfg["Configuration"]:::config
    end

    classDef control fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef api fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef hardware fill:#FFA500,stroke:#000,stroke-width:1px;
    classDef config fill:#D3D3D3,stroke:#000,stroke-width:1px;
```
