# hkucukdereli/vrfarm architecture

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

- Interactive diagram: https://gitdiagram.com/hkucukdereli/vrfarm
- Repository: https://github.com/hkucukdereli/vrfarm
- Video tour (about a minute): https://gitdiagram.com/hkucukdereli/vrfarm/video

## Overview

VRFarm coordinates browser-operated behavioral sessions across a controller and two Raspberry Pis. The controller configures rigs and experiments, deploys and starts sessions, and receives live events. The Leader prepares stimuli, runs trial stages, operates behavioral devices, records HDF5 data, and commands the Follower to render; session data is then consolidated and synchronized for analysis. The graph preserves documented calibration, diagnostics, and rig-health capabilities. Some subsystem wiring is based on the README because their source was not sampled.

Main entry points: [`engine/leader.py`](https://github.com/hkucukdereli/vrfarm/blob/main/engine/leader.py) (Trial engine), [`controller/app.py`](https://github.com/hkucukdereli/vrfarm/blob/main/controller/app.py) (Flask application), [`displayd/displayd.py`](https://github.com/hkucukdereli/vrfarm/blob/main/displayd/displayd.py) (Projector daemon), [`pi_api/api.py`](https://github.com/hkucukdereli/vrfarm/blob/main/pi_api/api.py) (Pi REST API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Controller"]
  node_controller_app["Flask application<br/>[app.py]"]
  node_experiment_ui["Experiment tab<br/>[experiment.py]"]
  node_setup_ui["Setup tab<br/>[setup.py]"]
  node_data_ui["Data tab<br/>[data.py]"]
  node_network_ui["Network tab<br/>[network.py]"]
  node_rig_registry["Rig registry<br/>[registry.py]"]
  node_event_demux["UDP event receiver<br/>[events.py]"]
end

subgraph group_session["Session Runtime"]
  node_pi_api["Pi REST API<br/>[api.py]"]
  node_leader["Trial engine<br/>[leader.py]"]
  node_stim_generator["Stimulus planner<br/>[stim_generator.py]"]
  node_devices["Behavioral devices"]
end

subgraph group_display["Display System"]
  node_follower["Projector daemon<br/>[displayd.py]"]
  node_renderer["Display renderer<br/>[renderer.py]"]
  node_dlp["DLP control<br/>[dlpc.py]"]
  node_calibration["Display calibration"]
  node_diagnostics["Display diagnostics"]
end

subgraph group_data["Data and Health"]
  node_session_hdf5[("Session HDF5")]
  node_consolidation["Session consolidation<br/>[consolidate.py]"]
  node_leader_data["Leader data access<br/>[leader_data.py]"]
  node_analysis["Analysis loaders<br/>[loaders.py]"]
  node_shepherd["Rig health monitor<br/>[shepherd.py]"]
end

node_operator(("Rig operator"))
node_browser(("Browser UI"))
node_leader_pi(("Leader Pi"))
node_follower_pi(("Follower Pi"))
node_controller_store[("Controller data storage")]

node_operator -->|"operates"| node_browser
node_browser -->|"requests"| node_controller_app
node_controller_app -->|"mounts"| node_experiment_ui
node_controller_app -->|"mounts"| node_setup_ui
node_controller_app -->|"mounts"| node_data_ui
node_controller_app -->|"mounts"| node_network_ui
node_controller_app -->|"starts receiver"| node_event_demux
node_experiment_ui -->|"loads rig"| node_rig_registry
node_setup_ui -->|"deploys via REST"| node_pi_api
node_experiment_ui -->|"controls session"| node_pi_api
node_pi_api -->|"starts process"| node_leader
node_leader -->|"builds plan"| node_stim_generator
node_leader -->|"operates"| node_devices
node_leader -->|"writes trials"| node_session_hdf5
node_leader -->|"sends SHOW/QUIT"| node_follower
node_follower -->|"dispatches render"| node_renderer
node_follower -->|"controls projector"| node_dlp
node_follower -->|"runs on"| node_follower_pi
node_leader -->|"runs on"| node_leader_pi
node_leader -->|"sends live events"| node_event_demux
node_event_demux -->|"demultiplexes events"| node_controller_app
node_calibration -.->|"calibrates display"| node_pi_api
node_diagnostics -.->|"checks output"| node_follower
node_data_ui -->|"inspects sessions"| node_leader_data
node_data_ui -->|"syncs data"| node_controller_store
node_leader_data -->|"reads session files"| node_leader_pi
node_session_hdf5 -->|"merges sidecars"| node_consolidation
node_consolidation -->|"transfers session"| node_controller_store
node_controller_store -->|"loads sessions"| node_analysis
node_shepherd -->|"probes status"| node_pi_api
node_shepherd -->|"monitors health"| node_leader_pi

click node_controller_app "https://github.com/hkucukdereli/vrfarm/blob/main/controller/app.py"
click node_experiment_ui "https://github.com/hkucukdereli/vrfarm/blob/main/controller/experiment.py"
click node_setup_ui "https://github.com/hkucukdereli/vrfarm/blob/main/controller/setup.py"
click node_data_ui "https://github.com/hkucukdereli/vrfarm/blob/main/controller/data.py"
click node_network_ui "https://github.com/hkucukdereli/vrfarm/blob/main/controller/network.py"
click node_rig_registry "https://github.com/hkucukdereli/vrfarm/blob/main/controller/registry.py"
click node_event_demux "https://github.com/hkucukdereli/vrfarm/blob/main/controller/events.py"
click node_pi_api "https://github.com/hkucukdereli/vrfarm/blob/main/pi_api/api.py"
click node_leader "https://github.com/hkucukdereli/vrfarm/blob/main/engine/leader.py"
click node_stim_generator "https://github.com/hkucukdereli/vrfarm/blob/main/shared/stim_generator.py"
click node_devices "https://github.com/hkucukdereli/vrfarm/tree/main/devices"
click node_follower "https://github.com/hkucukdereli/vrfarm/blob/main/displayd/displayd.py"
click node_renderer "https://github.com/hkucukdereli/vrfarm/blob/main/displayd/renderer.py"
click node_dlp "https://github.com/hkucukdereli/vrfarm/blob/main/displayd/dlpc.py"
click node_calibration "https://github.com/hkucukdereli/vrfarm/tree/main/display_calibration"
click node_diagnostics "https://github.com/hkucukdereli/vrfarm/tree/main/display_diagnostics"
click node_consolidation "https://github.com/hkucukdereli/vrfarm/blob/main/shared/consolidate.py"
click node_leader_data "https://github.com/hkucukdereli/vrfarm/blob/main/shared/leader_data.py"
click node_analysis "https://github.com/hkucukdereli/vrfarm/blob/main/analysis/loaders.py"
click node_shepherd "https://github.com/hkucukdereli/vrfarm/blob/main/shepherd/shepherd.py"

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_controller_app,node_experiment_ui,node_setup_ui,node_data_ui,node_network_ui,node_rig_registry,node_event_demux,node_browser toneBlue
class node_pi_api,node_leader,node_stim_generator,node_devices,node_controller_store toneAmber
class node_follower,node_renderer,node_dlp,node_calibration,node_diagnostics toneMint
class node_session_hdf5,node_consolidation,node_leader_data,node_analysis,node_shepherd toneRose
class node_operator,node_leader_pi,node_follower_pi toneIndigo
```

## Components

### Controller

- [Flask application](https://github.com/hkucukdereli/vrfarm/blob/main/controller/app.py): `controller/app.py`
- [Experiment tab](https://github.com/hkucukdereli/vrfarm/blob/main/controller/experiment.py): `controller/experiment.py`
- [Setup tab](https://github.com/hkucukdereli/vrfarm/blob/main/controller/setup.py): `controller/setup.py`
- [Data tab](https://github.com/hkucukdereli/vrfarm/blob/main/controller/data.py): `controller/data.py`
- [Network tab](https://github.com/hkucukdereli/vrfarm/blob/main/controller/network.py): `controller/network.py`
- [Rig registry](https://github.com/hkucukdereli/vrfarm/blob/main/controller/registry.py): `controller/registry.py`
- [UDP event receiver](https://github.com/hkucukdereli/vrfarm/blob/main/controller/events.py): `controller/events.py`

### Session Runtime

- [Pi REST API](https://github.com/hkucukdereli/vrfarm/blob/main/pi_api/api.py): `pi_api/api.py`
- [Trial engine](https://github.com/hkucukdereli/vrfarm/blob/main/engine/leader.py): `engine/leader.py`
- [Stimulus planner](https://github.com/hkucukdereli/vrfarm/blob/main/shared/stim_generator.py): `shared/stim_generator.py`
- [Behavioral devices](https://github.com/hkucukdereli/vrfarm/tree/main/devices): `devices`

### Display System

- [Projector daemon](https://github.com/hkucukdereli/vrfarm/blob/main/displayd/displayd.py): `displayd/displayd.py`
- [Display renderer](https://github.com/hkucukdereli/vrfarm/blob/main/displayd/renderer.py): `displayd/renderer.py`
- [DLP control](https://github.com/hkucukdereli/vrfarm/blob/main/displayd/dlpc.py): `displayd/dlpc.py`
- [Display calibration](https://github.com/hkucukdereli/vrfarm/tree/main/display_calibration): `display_calibration`
- [Display diagnostics](https://github.com/hkucukdereli/vrfarm/tree/main/display_diagnostics): `display_diagnostics`

### Data and Health

- **Session HDF5**
- [Session consolidation](https://github.com/hkucukdereli/vrfarm/blob/main/shared/consolidate.py): `shared/consolidate.py`
- [Leader data access](https://github.com/hkucukdereli/vrfarm/blob/main/shared/leader_data.py): `shared/leader_data.py`
- [Analysis loaders](https://github.com/hkucukdereli/vrfarm/blob/main/analysis/loaders.py): `analysis/loaders.py`
- [Rig health monitor](https://github.com/hkucukdereli/vrfarm/blob/main/shepherd/shepherd.py): `shepherd/shepherd.py`

### Other components

- **Rig operator**
- **Browser UI**
- **Leader Pi**
- **Follower Pi**
- **Controller data storage**

## Connections

- Rig operator → Browser UI: operates
- Browser UI → Flask application: requests
- Flask application → Experiment tab: mounts
- Flask application → Setup tab: mounts
- Flask application → Data tab: mounts
- Flask application → Network tab: mounts
- Flask application → UDP event receiver: starts receiver
- Experiment tab → Rig registry: loads rig
- Setup tab → Pi REST API: deploys via REST
- Experiment tab → Pi REST API: controls session
- Pi REST API → Trial engine: starts process
- Trial engine → Stimulus planner: builds plan
- Trial engine → Behavioral devices: operates
- Trial engine → Session HDF5: writes trials
- Trial engine → Projector daemon: sends SHOW/QUIT
- Projector daemon → Display renderer: dispatches render
- Projector daemon → DLP control: controls projector
- Projector daemon → Follower Pi: runs on
- Trial engine → Leader Pi: runs on
- Trial engine → UDP event receiver: sends live events
- UDP event receiver → Flask application: demultiplexes events
- Display calibration → Pi REST API: calibrates display
- Display diagnostics → Projector daemon: checks output
- Data tab → Leader data access: inspects sessions
- Data tab → Controller data storage: syncs data
- Leader data access → Leader Pi: reads session files
- Session HDF5 → Session consolidation: merges sidecars
- Session consolidation → Controller data storage: transfers session
- Controller data storage → Analysis loaders: loads sessions
- Rig health monitor → Pi REST API: probes status
- Rig health monitor → Leader Pi: monitors health