How tiqi-group/icon works
1. System boundary
ICON is a Python-based control plane for trapped-ion experiments. It sits between a user-facing React UI, Python experiment definitions from a separate “experiment library,” connected device services, and laboratory hardware/data stores.
2. Backend as the central coordinator
The icon.server package is the core runtime. It hosts the HTTP/WebSocket server, the scheduler, preprocessing/hardware/postprocessing workers, and all persistence access. Most meaningful state changes flow through this backend rather than directly between UI and hardware.
3. Frontend delivery and role
The React/TypeScript frontend lives in frontend/, but the production build is served by the backend from src/icon/server/frontend/. The UI is for configuration, device/parameter management, experiment submission, live job monitoring, and result visualization. In architecture terms, it is a client of the backend API plus live socket updates.
4. API layer
The backend exposes a set of controllers under src/icon/server/api/ for configuration, devices, experiments, parameters, scans, scheduler, status, and experiment data. An OpenAPI spec is included in docs/openapi.yaml, and there is also a generated Python client under src/icon/client/ for programmatic access.
5. Experiment execution pipeline
Experiment runs are not handled as a single monolithic function. They are split into three processing stages:
- Pre-processing prepares jobs and parameters.
- Hardware processing drives the actual hardware-facing execution.
- Post-processing collects and transforms results.
The scheduler coordinates these stages, and each stage has its own worker/task modules under src/icon/server/{pre_processing,hardware_processing,post_processing}/.
6. Device and parameter model
ICON manages both experiment parameters and externally provided device parameters. The frontend includes dedicated device and parameter screens, while the backend has device and parameters controllers plus repositories/models for device metadata. This boundary matters because scans can target not only experiment-local parameters but also remote device parameters exposed via services such as pydase.
7. Persistence split by data type
ICON uses different stores for different concerns:
- SQLite for job history, device metadata, experiment sources, and relational state.
- InfluxDB v1 for time-series parameter/state data.
- HDF5 for experiment result payloads.
The repository layer in src/icon/server/data_access/repositories/ mediates access to these stores, so most higher-level server components should be drawn as depending on repositories rather than directly on databases.
8. SQLite schema management
The SQLite schema is SQLAlchemy-based and versioned with Alembic. Startup runs migrations automatically, and the migration history under src/icon/server/data_access/db_context/sqlite/alembic/versions/ indicates that job tracking, device records, scan parameters, retries, repetitions, and related metadata are first-class durable entities.
9. Real-time updates
ICON uses Socket.IO/WebSocket-style communication for live state changes. The socket setup and emit queue live under src/icon/server/web_server/, which suggests asynchronous push updates from backend workers/scheduler to the UI for job progress, status changes, and live plots.
10. Configuration and control flow
The application is configured via a YAML file in ~/.config/icon/config.yaml by default. Settings can be edited either in that file or from the frontend settings page. This configuration influences server binding, backend integrations, and likely database/service endpoints, so it is a key architectural input to the whole runtime.
11. Experiment-library integration
A major architectural dependency is the external experiment library written for pycrystal. ICON parses that library to discover experiments and metadata, and it provides templates/helpers in src/icon/server/data_access/templates/ for extracting experiment and parameter information. In diagrams, this should appear as a separate upstream codebase feeding metadata into ICON, not as code owned by ICON itself.
12. Operational packaging
The repo supports two deployment modes: a packaged Linux binary and source-based execution with uv. Development also expects a separate InfluxDB instance via k8s/dev.yml. This means the runtime is a multi-process/server system with external services, not a self-contained single binary application.
Main entry points: repositories Repositories · scheduler Scheduler · api API Layer · web_server Web Server
Components 18
Frontend
React/TypeScript client served in production by the backend.
- Web UI · Configuration, device/parameter management, experiment submission, monitoring, and results.
frontend/src - Live Updates · Receives real-time job, status, and plot updates from the backend.
frontend/src/socket.ts
Backend
Python control plane coordinating API, scheduling, execution, and persistence.
- Python Client · Generated Python client for programmatic access to ICON APIs.
src/icon/client - API Layer · Configuration, devices, experiments, parameters, scans, scheduler, status, and data endpoints.
src/icon/server/api - Web Server · Hosts the server runtime and live push channel, including frontend asset serving.
src/icon/server/web_server - Scheduler · Coordinates experiment lifecycle and hands work to processing stages.
src/icon/server/scheduler - Pre-processing · Prepares jobs, parameters, and execution inputs.
src/icon/server/pre_processing - Hardware Exec · Drives hardware-facing execution and device interaction.
src/icon/server/hardware_processing - Post-processing · Collects, transforms, and finalizes experiment results.
src/icon/server/post_processing - Configuration · Runtime settings loaded from the user configuration file and editable from the UI.
src/icon/config/config.py
Persistence
Durable stores and repositories behind the server runtime.
- Repositories · Repository boundary mediating access to jobs, devices, parameters, experiment sources, and results.
src/icon/server/data_access/repositories - SQLite · Stores job history, device metadata, experiment sources, scan parameters, retries, and related state.
src/icon/server/data_access/db_context/sqlite - InfluxDB · Persists parameter and state time-series data.
src/icon/server/data_access/db_context/influxdb_v1.py - HDF5 · Stores experiment result payloads.
src/icon/server/utils/h5py.py - SQLite Models · SQLAlchemy models for jobs, runs, devices, experiment sources, and scan parameters.
src/icon/server/data_access/models/sqlite - Migrations · Alembic-managed SQLite schema evolution and startup migration path.
src/icon/server/data_access/db_context/sqlite/alembic/versions
External Systems
Upstream experiment metadata and laboratory services outside this repository.
- Experiment Library · Upstream pycrystal-based experiment definitions parsed for metadata and sequence generation.
- Device Services · Remote device and parameter services such as pydase-backed endpoints.
Connections 22
- Web UI → API Layer: uses · User actions are translated into API calls for configuration, devices, experiments, scans, and jobs.
- Live Updates → Web Server: subscribes · Receives live state, job progress, and plot updates over Socket.IO/WebSocket-style channels.
- Python Client → API Layer: calls · Programmatic access to backend endpoints via generated client bindings.
- Web Server → API Layer: hosts · The server runtime exposes the HTTP API and serves the built frontend assets.
- API Layer → Scheduler: controls · Scheduler endpoints start, inspect, and manage experiment execution.
- API Layer → Repositories: reads/writes · API controllers persist and fetch runtime state through repositories.
- Scheduler → Pre-processing: dispatches · Schedules preprocessing work before execution.
- Scheduler → Hardware Exec: dispatches · Hands prepared runs to the hardware-facing stage.
- Scheduler → Post-processing: dispatches · Triggers result collection and transformation after execution.
- Pre-processing → Repositories: uses · Reads experiment sources, parameters, and queued jobs through repositories.
- Hardware Exec → Device Services: drives · Interacts with connected device services during experiment execution.
- Hardware Exec → Repositories: records · Writes execution state and job progress through the data-access layer.
- Post-processing → Repositories: stores · Persists final job and result metadata through repositories.
- Repositories → SQLite: persists · Repository implementations backed by relational storage.
- Repositories → InfluxDB: persists · Repository implementations backed by time-series storage.
- Repositories → HDF5: persists · Repository implementations backed by result-file storage.
- SQLite Models → SQLite: maps to · ORM schema defines the durable relational entities.
- Migrations → SQLite: migrates · Alembic revisions keep the SQLite schema versioned and upgraded on startup.
- Configuration → Web Server: configures · Runtime settings affect server binding and integration endpoints.
- Experiment Library → Repositories: metadata source · Experiment discovery and parameter extraction feed ICON's repositories and templates.
- Experiment Library → Pre-processing: defines jobs · Experiment definitions become executable jobs during preprocessing.
- Web Server → Scheduler: emits status · Asynchronous emit queue pushes scheduler and worker events to connected clients.