# grantdpowell/integrated-lab-companion architecture

> Architecture diagram of the GitHub repository grantdpowell/integrated-lab-companion, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/grantdpowell/integrated-lab-companion
- Repository: https://github.com/grantdpowell/integrated-lab-companion

## Overview

##### What this project is (type + purpose)
From the file tree + README, this is a **lab companion system** consisting of:
- A **Windows desktop application** written in **Python** (`ILC Release X Source Code.py`) that provides the UI, experiment workflow, analysis, and “data management”.
- An **Arduino firmware** sketch (`ILC Release X Ard Source Code.ino`) that likely performs **data acquisition / instrument control** and streams measurements to the PC.
- A **Windows installer artifact** (`ILC Release X-Installer.msi`) produced via **cx_Freeze** (as stated in README).
- Supporting assets (`Images/`).

##### What the file structure implies architecturally
The repo is very “release-bundled” rather than a typical multi-folder source tree:
- A single monolithic Python file strongly suggests the desktop app code may be internally modular (classes/sections), but not split into packages.
- A single Arduino sketch suggests one firmware image.

##### What to extract from the README and represent explicitly
- **Modules**: data acquisition, processing, visualization (explicitly mentioned).
- **Python** as the core application language.
- **Database** exists and stores experimental data.
- **Packaging/Distribution**: cx_Freeze → executable → MSI installer.
- **Missing “description key”**: there is an external secret/config element not in source; show as “Config/License/Key material (not in repo)”.

##### ILC Desktop App (Python)
- UI Layer (experiment workflow, operator controls)
- Data Acquisition Client (talks to Arduino)
- Processing/Analysis Module
- Visualization/Plotting Module
- Data Management Module (CRUD/query/export)
- Configuration/Secrets Loader (“description key” not shipped)

##### Local Persistence
- “Experiment Database” (unknown type; annotate as e.g., “SQLite / local DB / file-based DB”)

**Device / Embedded layer**
##### Arduino Firmware
- Sensor/measurement acquisition
- Signal conditioning (if applicable)
- Command handler (receives control commands from PC)
- Data streaming

**Connectivity layer**

##### Packaging & Installer
- Python source → cx_Freeze → EXE → MSI
- Drivers prerequisite (README mentions drivers; show as “USB/Serial driver dependency”)

- **User → ILC UI**
- “starts experiment”, “configures parameters”, “views plots”
- **ILC App → Arduino Firmware**
- “control commands” (start/stop, set sample rate, calibration, etc.)
- **Arduino Firmware → ILC App**
- “measurement stream” (timestamped samples, status frames)
- **ILC App ↔ Database**
- “store experiment runs”, “query history”, “retrieve results”
- **ILC App → Visualization**
- internally: “processed data → plots”
- **ILC App → Export (optional)**
- “reports / datasets”
- **Installer/MSI → Windows PC**
- “deploy app + dependencies”
- **Windows drivers → USB link**

##### Architectural patterns/design principles

- **Layered architecture** inside the desktop app:
- Presentation (UI)
- Application/Service layer (experiment orchestration)
- Infrastructure (device comms + database)
- **Modular responsibilities** (as README says): Acquisition, Processing, Visualization, Data Management
- **Boundary between embedded real-time acquisition** (Arduino) and **non-real-time analysis/UI** (PC)

##### Real-world hardware boundary
- Arduino and any sensors/instruments in a separate “Physical Lab Bench” zone.
##### Data lifecycle
- Acquisition → buffering → processing → visualization → persistence → retrieval/export.
##### Operational concerns
- Drivers, COM port selection, calibration, and configuration keys (even if conceptual).

- User, Windows PC app, Arduino device, database (as internal), external dependencies (drivers).
- Break the Python app into the modules named above (Acquisition/Processing/Visualization/Data Mgmt/UI/Config).
- Python source + assets → cx_Freeze build → EXE/MSI → installed app + driver prerequisites.

- In `ILC Release X Source Code.py`:
- Which GUI framework (Tkinter/PyQt/etc)
- Whether DB is SQLite (`sqlite3`), files (`json/csv`), or external service
- Which serial library (`pyserial`) and the message format
- In `.ino`:
- Serial baud rate, framing (CSV lines, binary packets), supported commands
- Sensor pins / peripheral interfaces (I2C/SPI/ADC)
- Installer:
- Whether it bundles Python runtime, drivers, and DB initialization

Confirmed facts; for unknowns, annotate explicitly (“TBD/unknown”) rather than guessing.

## Diagram (Mermaid)

```mermaid
flowchart TD

%% =======================
%% Zones / Swimlanes
%% =======================
subgraph "User"
  U["Lab Operator"]:::external
end

subgraph "Windows PC (Runtime)"
  direction TB

  subgraph "ILC Desktop App (Python)"
    direction TB
    UI["UI Layer\n(Experiment workflow + operator controls)\nPython GUI toolkit (unknown)"]:::app
    ORCH["Experiment Orchestrator\n(State machine / run control)"]:::app

    subgraph "Core Modules"
      direction TB
      ACQ["Data Acquisition Client\n(PC↔Arduino comms)"]:::app
      PROC["Processing / Analysis Module\n(Filter, compute metrics)"]:::app
      VIZ["Visualization / Plotting Module\n(Charts, trends)"]:::app
      DM["Data Management Module\n(CRUD / query / export)"]:::app
      CFG["Configuration / Secrets Loader\n('description key' not in repo)"]:::config
    end

    UI -->|"drives"| ORCH
    ORCH -->|"controls"| ACQ
    ORCH -->|"routes_data"| PROC
    PROC -->|"processed_data"| VIZ
    ORCH -->|"store/retrieve"| DM
    CFG -->|"loads_config"| ORCH
  end

  subgraph "Local Persistence"
    direction TB
    DB[("Experiment Database\nSQLite / local DB / file-based DB (unknown)")]:::db
    EXP["Exported Outputs\n(CSV/PDF/etc - if supported)"]:::artifact
  end

  DM -->|"SQL/records (unknown)"| DB
  DM -->|"export_reports/datasets"| EXP
end

subgraph "Connectivity"
  direction TB
  LINK["PC ↔ Arduino Link\nUSB Serial (COM port) (most likely)"]:::link
  DRV["USB/Serial Driver Dependency\n(Windows prerequisite)"]:::dependency
  DRV -.->|"required_for"| LINK
end

subgraph "Hardware (Physical Lab Bench)"
  direction TB
  ARD["Arduino Firmware\n(Data acquisition + instrument control)"]:::firmware
  SENS["Sensors / Instruments\n(ADC/I2C/SPI - board dependent)"]:::hardware
  SENS -->|"signals"| ARD
end

subgraph "Build & Distribution"
  direction TB
  README["Documentation\n(Modules, build notes, DB claims)"]:::doc
  SRC["Python Source\n(monolithic file)"]:::source
  ASSETS["Supporting Assets\n(images)"]:::asset
  BUILD["cx_Freeze Packaging\n(build step)"]:::build
  EXE["Windows Executable\n(bundled runtime)"]:::build
  MSI["Windows Installer (MSI)"]:::artifact

  SRC -->|"package_with"| BUILD
  ASSETS -->|"bundle"| BUILD
  BUILD -->|"produces"| EXE
  EXE -->|"wraps_into"| MSI
end

%% =======================
%% Cross-zone interactions (numbered key flows)
%% =======================
U -->|"1)configure_experiment"| UI
U -->|"2)start/stop_run"| UI
UI -->|"views_plots"| VIZ

ACQ -->|"USB_serial/commands\n(start,rate,calibrate)"| LINK
LINK -->|"control_frames"| ARD
ARD -->|"3)measurement_stream\n(samples,status)"| LINK
LINK -->|"USB_serial/frames"| ACQ

ACQ -->|"4)raw_samples"| PROC
PROC -->|"metrics/results"| DM
DM -->|"5)persist_results"| DB

MSI -->|"deploys_app"| UI
MSI -->|"installs_assets"| ASSETS
MSI -.->|"may_require"| DRV

README -.->|"describes_architecture"| SRC

%% =======================
%% Click events (component_mapping)
%% =======================
click UI "https://github.com/grantdpowell/integrated-lab-companion/blob/main/ILC Release X Source Code.py"
click ORCH "https://github.com/grantdpowell/integrated-lab-companion/blob/main/ILC Release X Source Code.py"
click ACQ "https://github.com/grantdpowell/integrated-lab-companion/blob/main/ILC Release X Source Code.py"
click PROC "https://github.com/grantdpowell/integrated-lab-companion/blob/main/ILC Release X Source Code.py"
click VIZ "https://github.com/grantdpowell/integrated-lab-companion/blob/main/ILC Release X Source Code.py"
click DM "https://github.com/grantdpowell/integrated-lab-companion/blob/main/ILC Release X Source Code.py"
click CFG "https://github.com/grantdpowell/integrated-lab-companion/blob/main/ILC Release X Source Code.py"
click ARD "https://github.com/grantdpowell/integrated-lab-companion/blob/main/ILC Release X Ard Source Code.ino"
click MSI "https://github.com/grantdpowell/integrated-lab-companion/blob/main/ILC Release X-Installer.msi"
click ASSETS "https://github.com/grantdpowell/integrated-lab-companion/tree/main/Images/"
click README "https://github.com/grantdpowell/integrated-lab-companion/blob/main/README.md"
click SRC "https://github.com/grantdpowell/integrated-lab-companion/blob/main/ILC Release X Source Code.py"

%% =======================
%% Styles (color-coded)
%% =======================
classDef external fill:#E9F2FF,stroke:#2B6CB0,color:#0B2545,stroke-width:1.5px
classDef app fill:#D6ECFF,stroke:#1D4ED8,color:#0B1B3A,stroke-width:1.5px
classDef config fill:#FDE68A,stroke:#B45309,color:#3A2A00,stroke-width:1.5px
classDef firmware fill:#FFD7B5,stroke:#C2410C,color:#3A1F00,stroke-width:1.5px
classDef hardware fill:#FFE6D5,stroke:#9A3412,color:#3A1F00,stroke-width:1.5px
classDef db fill:#D1FAE5,stroke:#047857,color:#064E3B,stroke-width:1.5px
classDef build fill:#E5E7EB,stroke:#4B5563,color:#111827,stroke-width:1.5px
classDef artifact fill:#F3F4F6,stroke:#6B7280,color:#111827,stroke-width:1.5px
classDef dependency fill:#EFEFEF,stroke:#6B7280,color:#111827,stroke-width:1.5px,stroke-dasharray: 4 3
classDef link fill:#E0F2FE,stroke:#0284C7,color:#0B2545,stroke-width:1.5px
classDef doc fill:#FFF7ED,stroke:#C2410C,color:#3A1F00,stroke-width:1.5px
classDef source fill:#F1F5F9,stroke:#334155,color:#0F172A,stroke-width:1.5px
classDef asset fill:#F5F3FF,stroke:#6D28D9,color:#1F1147,stroke-width:1.5px
```
