# aicell-lab/squid-control architecture

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

- Interactive diagram: https://gitdiagram.com/aicell-lab/squid-control
- Repository: https://github.com/aicell-lab/squid-control

## Overview

##### Major Components
- Squid Control Core:
- Includes the primary control logic found in the squid_control directory.
- Contains modules for controlling different cameras (e.g., camera_TIS.py, camera_default.py, camera_flir.py, camera_toupcam.py), GUI components, device configuration utility, and hardware interfacing (microcontroller, spectrometer, etc.).
- Houses configuration files (such as configuration_HCS_v2.ini, focus_camera_configurations.xml, uc2_fucci_illumination_configurations.xml) to configure device behavior.

- Hypha Integration Layer:
- Located in hypha_tools as well as the start_hypha_service.py script.
- Provides services for artifact management (e.g., dataset creation, image tile collection) and chatbot functions to register remote procedure calls via Hypha-RPC.
- Serves as the bridge to the external Hypha framework, enabling advanced automation and extensibility.

- CLI/Entry Points and Scripts:
- The squid_control/__main__.py acts as the entry point when executing “python -m squid_control”.
- Scripts in the scripts directory offer additional functionality for desktop launcher setup, camera listing, processing coordinates, and other custom utilities.

- Deployment and CI/CD:
- Docker-related files (Dockerfile in the docker directory) and GitHub workflows (.github/workflows) indicate containerization and CI/CD pipeline to deploy or publish the package (including PyPi publication).

- Documentation and Resources:
- The docs directory contains installation guides, tutorials (including the Hypha tutorial), and additional resources (like sample coordinates CSV) that explain usage and set up.

##### Relationships and Interactions
- The user interacts with the application via the CLI (or via GUI modules inside squid_control/control/gui.py) which then calls into the Squid Control Core for microscope operation.
- The control modules (in squid_control/control) communicate with various hardware drivers for cameras, microcontrollers, and peripherals.
- In simulation mode, the application can modify its behavior (triggered via command-line switches) but still follows the same control flow, using simulated data (as evidenced by sample CSVs and XML configurations).
- The Hypha integration layer (via hypha_tools and start_hypha_service.py) registers a Hypha service and supports a chatbot to allow remote procedure calls and advanced automation.
- Auxiliary scripts provide support and tooling that can be used independently or as part of the control flow to generate configurations, stitch images, or publish artifacts.

##### Architectural Patterns and Design Principles
- Modular Breakdown: The clear separation between the device control (squid_control), integration tools (hypha_tools), and utility scripts highlights a modular design that follows separation of concerns.
- Extensibility: The inclusion of custom multipoint script functionality and plugin-like integration of Hypha services shows design for extensibility.
- Configuration-Driven Behavior: The usage of various configuration files (INI, XML) and scripts for dynamic configuration indicates a flexible, configurable system.
- Containerization and CI/CD: The Docker and GitHub Actions configuration underline modern DevOps practices.

## Diagram (Mermaid)

```mermaid
flowchart TD
    User["User"]:::user
    CLI["CLI/Entry Point"]:::cli
    User --> CLI

    subgraph "Squid Control Core"
        SC_Controller["Core Controller"]:::core
        CAM["Camera Modules"]:::camera
        GUI1["GUI (gui.py)"]:::gui
        GUI2["GUI (gui_hcs.py)"]:::gui
        CFG1["Configuration (HCS_v2.ini)"]:::config
        CFG2["Focus Camera Config (XML)"]:::config
        CFG3["Illumination Config (XML)"]:::config
    end
    CLI --> SC_Controller

    subgraph "Hypha Integration"
        HYP_tools["Hypha Tools"]:::hypha
        HYP_service["Hypha Service"]:::hypha
    end
    SC_Controller -->|"RPC"| HYP_service
    SC_Controller -->|"Integrates"| HYP_tools

    US["Utility Scripts"]:::utility
    SC_Controller -->|"UtilCalls"| US

    subgraph "Deployment & CI/CD"
        DOCKER["Docker"]:::deploy
        CI["CI/CD Workflows"]:::deploy
    end
    US -->|"Deploys"| DOCKER
    DOCKER -->|"CI/CD"| CI

    DOC["Documentation & Resources"]:::docs
    CI --> DOC

    classDef user fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef cli fill:#D6EAF8,stroke:#2874A6,stroke-width:2px;
    classDef core fill:#A9DFBF,stroke:#1E8449,stroke-width:2px;
    classDef camera fill:#7FB3D5,stroke:#2E86C1,stroke-width:2px;
    classDef gui fill:#85C1E9,stroke:#2471A3,stroke-width:2px;
    classDef config fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef hypha fill:#F5CBA7,stroke:#CA6F1E,stroke-width:2px;
    classDef utility fill:#D7BDE2,stroke:#7D3C98,stroke-width:2px;
    classDef deploy fill:#F1948A,stroke:#C0392B,stroke-width:2px;
    classDef docs fill:#F7DC6F,stroke:#AF601A,stroke-width:2px;

    click CLI "https://github.com/aicell-lab/squid-control/blob/main/squid_control/__main__.py"
    click SC_Controller "https://github.com/aicell-lab/squid-control/blob/main/squid_control/squid_controller.py"
    click CAM "https://github.com/aicell-lab/squid-control/tree/main/squid_control/control/camera"
    click GUI1 "https://github.com/aicell-lab/squid-control/blob/main/squid_control/control/gui.py"
    click GUI2 "https://github.com/aicell-lab/squid-control/blob/main/squid_control/control/gui_hcs.py"
    click CFG1 "https://github.com/aicell-lab/squid-control/blob/main/squid_control/configuration_HCS_v2.ini"
    click CFG2 "https://github.com/aicell-lab/squid-control/blob/main/squid_control/focus_camera_configurations.xml"
    click CFG3 "https://github.com/aicell-lab/squid-control/blob/main/squid_control/uc2_fucci_illumination_configurations.xml"
    click HYP_tools "https://github.com/aicell-lab/squid-control/tree/main/hypha_tools"
    click HYP_service "https://github.com/aicell-lab/squid-control/blob/main/start_hypha_service.py"
    click US "https://github.com/aicell-lab/squid-control/tree/main/scripts"
    click DOCKER "https://github.com/aicell-lab/squid-control/tree/main/docker/Dockerfile"
    click CI "https://github.com/aicell-lab/squid-control/blob/main/.github/workflows/docker-publish.yml"
    click DOC "https://github.com/aicell-lab/squid-control/tree/main/docs"
```
