# hacker-fab/2d_crystal_stacking architecture

> Architecture diagram of the GitHub repository hacker-fab/2d_crystal_stacking, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hacker-fab/2d_crystal_stacking
- Repository: https://github.com/hacker-fab/2d_crystal_stacking

## Overview

This is a web-based microscope control system for crystal alignment and stacking. The principal workflow runs from the dashboard through FastAPI endpoints to device abstractions and, where available, camera or stage hardware. Separate control branches cover camera imaging and calibration, nanopositioning, rotation, carousel feeding, thermal control, and vacuum. The README and sampled source support the main camera and nanopositioner paths; wiring details for several other branches are documented but their device implementations were not sampled.

Main entry points: [`app/web.py`](https://github.com/hacker-fab/2d_crystal_stacking/blob/Carousel/app/web.py) (FastAPI application), [`devices/base_device.py`](https://github.com/hacker-fab/2d_crystal_stacking/blob/Carousel/devices/base_device.py) (Device base), [`app/camera_service.py`](https://github.com/hacker-fab/2d_crystal_stacking/blob/Carousel/app/camera_service.py) (Camera service), [`devices/nanopositioner.py`](https://github.com/hacker-fab/2d_crystal_stacking/blob/Carousel/devices/nanopositioner.py) (Nanopositioner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User Interface"]
  node_dashboard["Control dashboard<br/>[index.html]"]
  node_client["Dashboard API client<br/>[app.js]"]
end

subgraph group_server["Web API"]
  node_entry["Server entry<br/>[main.py]"]
  node_web["FastAPI application<br/>[web.py]"]
  node_camera_service["Camera service<br/>[camera_service.py]"]
  node_nano_router["Stage API<br/>[router.py]"]
  node_rotation_router["Rotation API<br/>[router.py]"]
  node_carousel_router["Carousel API<br/>[router.py]"]
  node_thermal_router["Thermal API<br/>[router.py]"]
  node_vacuum_router["Vacuum API<br/>[router.py]"]
end

subgraph group_devices["Device Control"]
  node_base["Device base<br/>[base_device.py]"]
  node_camera_device["Camera state<br/>[camera.py]"]
  node_nano_device["Nanopositioner<br/>[nanopositioner.py]"]
  node_rotation_device["Rotation plate<br/>[rotation.py]"]
  node_carousel_device["Carousel feeder<br/>[carousel.py]"]
  node_thermal_device["Thermal plate<br/>[thermal.py]"]
  node_vacuum_device["Vacuum pump<br/>[vacuum.py]"]
end

subgraph group_hardware["Hardware Integration"]
  node_oms["OMS channel<br/>[oms_channel.py]"]
  node_camera_backends["Camera backends"]
end

node_user(("Microscope operator"))
node_stage_controller{{"Stage controller"}}
node_camera_hardware{{"Camera hardware"}}

node_user -->|"operates"| node_dashboard
node_dashboard -->|"loads"| node_client
node_client -->|"calls API"| node_web
node_entry -->|"runs"| node_web
node_web -->|"serves camera"| node_camera_service
node_web -->|"mounts routes"| node_nano_router
node_web -->|"mounts routes"| node_rotation_router
node_web -->|"mounts routes"| node_carousel_router
node_web -->|"mounts routes"| node_thermal_router
node_web -->|"mounts routes"| node_vacuum_router
node_camera_service -->|"extends"| node_camera_device
node_camera_service -->|"controls"| node_camera_backends
node_camera_backends -->|"captures frames"| node_camera_hardware
node_nano_router -->|"dispatches commands"| node_nano_device
node_nano_device -->|"calls interface"| node_oms
node_oms -->|"communicates"| node_stage_controller
node_rotation_router -->|"dispatches commands"| node_rotation_device
node_carousel_router -->|"dispatches feed"| node_carousel_device
node_thermal_router -->|"dispatches controls"| node_thermal_device
node_vacuum_router -->|"dispatches controls"| node_vacuum_device
node_camera_device -->|"inherits"| node_base
node_nano_device -->|"inherits"| node_base
node_rotation_device -->|"inherits"| node_base
node_carousel_device -->|"inherits"| node_base
node_thermal_device -->|"inherits"| node_base
node_vacuum_device -->|"inherits"| node_base

click node_dashboard "https://github.com/hacker-fab/2d_crystal_stacking/blob/Carousel/templates/index.html"
click node_client "https://github.com/hacker-fab/2d_crystal_stacking/blob/Carousel/static/app.js"
click node_entry "https://github.com/hacker-fab/2d_crystal_stacking/blob/Carousel/main.py"
click node_web "https://github.com/hacker-fab/2d_crystal_stacking/blob/Carousel/app/web.py"
click node_camera_service "https://github.com/hacker-fab/2d_crystal_stacking/blob/Carousel/app/camera_service.py"
click node_nano_router "https://github.com/hacker-fab/2d_crystal_stacking/blob/Carousel/nanopositioner/router.py"
click node_rotation_router "https://github.com/hacker-fab/2d_crystal_stacking/blob/Carousel/rotation_plate/router.py"
click node_carousel_router "https://github.com/hacker-fab/2d_crystal_stacking/blob/Carousel/carousel/router.py"
click node_thermal_router "https://github.com/hacker-fab/2d_crystal_stacking/blob/Carousel/thermal_plate/router.py"
click node_vacuum_router "https://github.com/hacker-fab/2d_crystal_stacking/blob/Carousel/vacuum/router.py"
click node_base "https://github.com/hacker-fab/2d_crystal_stacking/blob/Carousel/devices/base_device.py"
click node_camera_device "https://github.com/hacker-fab/2d_crystal_stacking/blob/Carousel/devices/camera.py"
click node_nano_device "https://github.com/hacker-fab/2d_crystal_stacking/blob/Carousel/devices/nanopositioner.py"
click node_rotation_device "https://github.com/hacker-fab/2d_crystal_stacking/blob/Carousel/devices/rotation.py"
click node_carousel_device "https://github.com/hacker-fab/2d_crystal_stacking/blob/Carousel/devices/carousel.py"
click node_thermal_device "https://github.com/hacker-fab/2d_crystal_stacking/blob/Carousel/devices/thermal.py"
click node_vacuum_device "https://github.com/hacker-fab/2d_crystal_stacking/blob/Carousel/devices/vacuum.py"
click node_oms "https://github.com/hacker-fab/2d_crystal_stacking/blob/Carousel/devices/oms_channel.py"
click node_camera_backends "https://github.com/hacker-fab/2d_crystal_stacking/tree/Carousel/camera"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_dashboard,node_client toneBlue
class node_entry,node_web,node_camera_service,node_nano_router,node_rotation_router,node_carousel_router,node_thermal_router,node_vacuum_router toneAmber
class node_base,node_camera_device,node_nano_device,node_rotation_device,node_carousel_device,node_thermal_device,node_vacuum_device toneMint
class node_oms,node_camera_backends toneRose
class node_user,node_stage_controller,node_camera_hardware toneIndigo
```

## Components

### User Interface

- [Control dashboard](https://github.com/hacker-fab/2d_crystal_stacking/blob/Carousel/templates/index.html): `templates/index.html`
- [Dashboard API client](https://github.com/hacker-fab/2d_crystal_stacking/blob/Carousel/static/app.js): `static/app.js`

### Web API

- [Server entry](https://github.com/hacker-fab/2d_crystal_stacking/blob/Carousel/main.py): `main.py`
- [FastAPI application](https://github.com/hacker-fab/2d_crystal_stacking/blob/Carousel/app/web.py): `app/web.py`
- [Camera service](https://github.com/hacker-fab/2d_crystal_stacking/blob/Carousel/app/camera_service.py): `app/camera_service.py`
- [Stage API](https://github.com/hacker-fab/2d_crystal_stacking/blob/Carousel/nanopositioner/router.py): `nanopositioner/router.py`
- [Rotation API](https://github.com/hacker-fab/2d_crystal_stacking/blob/Carousel/rotation_plate/router.py): `rotation_plate/router.py`
- [Carousel API](https://github.com/hacker-fab/2d_crystal_stacking/blob/Carousel/carousel/router.py): `carousel/router.py`
- [Thermal API](https://github.com/hacker-fab/2d_crystal_stacking/blob/Carousel/thermal_plate/router.py): `thermal_plate/router.py`
- [Vacuum API](https://github.com/hacker-fab/2d_crystal_stacking/blob/Carousel/vacuum/router.py): `vacuum/router.py`

### Device Control

- [Device base](https://github.com/hacker-fab/2d_crystal_stacking/blob/Carousel/devices/base_device.py): `devices/base_device.py`
- [Camera state](https://github.com/hacker-fab/2d_crystal_stacking/blob/Carousel/devices/camera.py): `devices/camera.py`
- [Nanopositioner](https://github.com/hacker-fab/2d_crystal_stacking/blob/Carousel/devices/nanopositioner.py): `devices/nanopositioner.py`
- [Rotation plate](https://github.com/hacker-fab/2d_crystal_stacking/blob/Carousel/devices/rotation.py): `devices/rotation.py`
- [Carousel feeder](https://github.com/hacker-fab/2d_crystal_stacking/blob/Carousel/devices/carousel.py): `devices/carousel.py`
- [Thermal plate](https://github.com/hacker-fab/2d_crystal_stacking/blob/Carousel/devices/thermal.py): `devices/thermal.py`
- [Vacuum pump](https://github.com/hacker-fab/2d_crystal_stacking/blob/Carousel/devices/vacuum.py): `devices/vacuum.py`

### Hardware Integration

- [OMS channel](https://github.com/hacker-fab/2d_crystal_stacking/blob/Carousel/devices/oms_channel.py): `devices/oms_channel.py`
- [Camera backends](https://github.com/hacker-fab/2d_crystal_stacking/tree/Carousel/camera): `camera`

### Other components

- **Microscope operator**
- **Stage controller**
- **Camera hardware**

## Connections

- Microscope operator → Control dashboard: operates
- Control dashboard → Dashboard API client: loads
- Dashboard API client → FastAPI application: calls API
- Server entry → FastAPI application: runs
- FastAPI application → Camera service: serves camera
- FastAPI application → Stage API: mounts routes
- FastAPI application → Rotation API: mounts routes
- FastAPI application → Carousel API: mounts routes
- FastAPI application → Thermal API: mounts routes
- FastAPI application → Vacuum API: mounts routes
- Camera service → Camera state: extends
- Camera service → Camera backends: controls
- Camera backends → Camera hardware: captures frames
- Stage API → Nanopositioner: dispatches commands
- Nanopositioner → OMS channel: calls interface
- OMS channel → Stage controller: communicates
- Rotation API → Rotation plate: dispatches commands
- Carousel API → Carousel feeder: dispatches feed
- Thermal API → Thermal plate: dispatches controls
- Vacuum API → Vacuum pump: dispatches controls
- Camera state → Device base: inherits
- Nanopositioner → Device base: inherits
- Rotation plate → Device base: inherits
- Carousel feeder → Device base: inherits
- Thermal plate → Device base: inherits
- Vacuum pump → Device base: inherits