# battery-data-alliance/pyctiarbin architecture

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

- Interactive diagram: https://gitdiagram.com/battery-data-alliance/pyctiarbin
- Repository: https://github.com/battery-data-alliance/pyctiarbin

## Overview

##### Project type and purpose
- This is an open-source Python library (not a full-stack web app) whose core job is to provide a high-level “CyclerInterface” and “ChannelInterface” over TCP to Arbin cyclers via their Console TCP/IP Interface (CTI).
- It also includes an “ArbinSpoofer” local TCP server for testing in lieu of a real cycler.

##### File structure
- Top Level
– .github/workflows: CI pipelines (Release, testing)
– docs/: user and protocol docs + pydoc-generated API docs
– pyctiarbin/ : the library package
– tests/: test suite, including example messages and spoofer tests
– demo_notebook.ipynb: usage demo

- pyctiarbin/ sub-packages
– arbinspoofer/: server emulator (ArbinSpoofer)
– channel_interface.py: ChannelInterface class (read/write per‐channel)
– cycler_interface.py: CyclerInterface class (read‐only cycler status)
– messages.py: message definitions, (de)serialization for CTI protocol

##### README for additional insights
- Two main client classes: CyclerInterface & ChannelInterface
- Configuration via dict + .env for credentials
- Underlying communications: raw TCP sockets, protocol messages
- Testing via ArbinSpoofer

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Application
    ClientApp["Client Application"]:::external

    %% Pyctiarbin Library Package
    subgraph "pyctiarbin Package"
        direction TB
        CyclerIF["CyclerInterface"]:::api
        ChannelIF["ChannelInterface"]:::api
        MessageLayer["Message Factory/Parser"]:::internal
        ConfigLoader["Config & Env Loader"]:::internal
        subgraph "ArbinSpoofer Module"
            direction TB
            SpooferFile["ArbinSpoofer Server"]:::internal
        end
    end

    %% External CTI Server
    CTIServer["Arbin CTI Server"]:::external

    %% Testing Suite
    Tests["Test Suite (pytest)"]:::testing
    ExampleMsgs["Example Protocol Messages"]:::testing

    %% CI/CD Pipelines
    subgraph "CI/CD & Packaging"
        direction TB
        CI1["GitHub Actions: Testing"]:::ci
        CI2["GitHub Actions: Release"]:::ci
        Setup["setup.py & Metadata"]:::ci
        Requirements["requirements.txt"]:::ci
        Manifest["MANIFEST.in"]:::ci
    end

    %% Documentation and Demo
    Docs["User & API Documentation"]:::docs
    Demo["Demo Notebook"]:::docs

    %% Data Flows
    ClientApp -->|"instantiate"| CyclerIF
    ClientApp -->|"instantiate"| ChannelIF
    CyclerIF -->|"build message"| MessageLayer
    ChannelIF -->|"build message"| MessageLayer
    MessageLayer -->|"send over TCP"| CTIServer
    CTIServer -->|"receive binary"| MessageLayer
    MessageLayer -->|"parse message"| CyclerIF
    MessageLayer -->|"parse message"| ChannelIF
    %% Testing with Spoofer
    CyclerIF -->|"for testing"| SpooferFile
    ChannelIF -->|"for testing"| SpooferFile
    SpooferFile -->|"respond binary"| MessageLayer
    %% CI/CD Relations
    CI1 --> Tests
    Tests --> SpooferFile
    Tests --> ExampleMsgs
    CI2 --> Setup
    CI2 --> Requirements
    CI2 --> Manifest
    %% Docs and Demo
    Docs --> CyclerIF
    Docs --> ChannelIF
    Docs --> MessageLayer
    Docs --> SpooferFile
    Demo --> ClientApp

    %% Click Events
    click CyclerIF "https://github.com/battery-data-alliance/pyctiarbin/blob/main/pyctiarbin/cycler_interface.py"
    click ChannelIF "https://github.com/battery-data-alliance/pyctiarbin/blob/main/pyctiarbin/channel_interface.py"
    click MessageLayer "https://github.com/battery-data-alliance/pyctiarbin/blob/main/pyctiarbin/messages.py"
    click SpooferFile "https://github.com/battery-data-alliance/pyctiarbin/blob/main/pyctiarbin/arbinspoofer/arbin_spoofer.py"
    click SpooferFile "https://github.com/battery-data-alliance/pyctiarbin/tree/main/pyctiarbin/arbinspoofer/"
    click ConfigLoader "https://github.com/battery-data-alliance/pyctiarbin/blob/main/pyctiarbin/__init__.py"
    click Tests "https://github.com/battery-data-alliance/pyctiarbin/tree/main/tests/"
    click ExampleMsgs "https://github.com/battery-data-alliance/pyctiarbin/tree/main/tests/example_messages/"
    click CI1 "https://github.com/battery-data-alliance/pyctiarbin/blob/main/.github/workflows/pycti.yml"
    click CI2 "https://github.com/battery-data-alliance/pyctiarbin/blob/main/.github/workflows/Release.yml"
    click Setup "https://github.com/battery-data-alliance/pyctiarbin/blob/main/setup.py"
    click Requirements "https://github.com/battery-data-alliance/pyctiarbin/blob/main/requirements.txt"
    click Manifest "https://github.com/battery-data-alliance/pyctiarbin/blob/main/MANIFEST.in"
    click Docs "https://github.com/battery-data-alliance/pyctiarbin/tree/main/docs/pycti/"
    click Demo "https://github.com/battery-data-alliance/pyctiarbin/blob/main/demo_notebook.ipynb"

    %% Styles
    classDef api fill:#FFD700,stroke:#333,stroke-width:1px
    classDef internal fill:#ADFF2F,stroke:#333,stroke-width:1px
    classDef external fill:#87CEFA,stroke:#333,stroke-width:1px
    classDef testing fill:#FFB6C1,stroke:#333,stroke-width:1px
    classDef ci fill:#FFA500,stroke:#333,stroke-width:1px
    classDef docs fill:#DDA0DD,stroke:#333,stroke-width:1px
```
