# chenyvhang/cyber-larva architecture

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

- Interactive diagram: https://gitdiagram.com/chenyvhang/cyber-larva
- Repository: https://github.com/chenyvhang/cyber-larva

## Overview

CyberLarva is an interactive closed-loop larval locomotion model, with a local scientific build and a reduced browser-only demo. The principal workflow senses habitat conditions, drives neural activity and segmental locomotor control, simulates body motion and contact, then returns pose and contact information to the sensory loop. Users can also edit habitats and silence neurons. The README documents these capabilities; some internal controller and browser wiring lies in unsampled source, so those links are shown only where documented.

Main entry points: [`cyberlarva/connectome.py`](https://github.com/chenyvhang/cyber-larva/blob/main/cyberlarva/connectome.py) (Sparse neural network), [`server.py`](https://github.com/chenyvhang/cyber-larva/blob/main/server.py) (Local API and loop), [`cyberlarva/world.py`](https://github.com/chenyvhang/cyber-larva/blob/main/cyberlarva/world.py) (Habitat and senses), [`cyberlarva/physics.py`](https://github.com/chenyvhang/cyber-larva/blob/main/cyberlarva/physics.py) (MuJoCo body physics)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_browser["3D interface<br/>[main.js]"]
  node_demo["Browser demo API<br/>[demo-api.js]"]
  node_server["Local API and loop<br/>[server.py]"]
end

subgraph group_habitat["Habitat and sensing"]
  node_world["Habitat and senses<br/>[world.py]"]
end

subgraph group_control["Neural and motor control"]
  node_brain["Sparse neural network<br/>[connectome.py]"]
  node_vnc["Segmental motor control<br/>[physics.py]"]
end

subgraph group_simulation["Body simulation"]
  node_physics["MuJoCo body physics<br/>[physics.py]"]
end

subgraph group_data["Scientific data"]
  node_topology[("Connectome topology")]
  node_calibration["Trajectory calibration"]
  node_neurons["Neuron identities"]
end

node_user(("Experimenter"))

node_user -->|"interacts"| node_browser
node_browser -.->|"requests state"| node_server
node_browser -->|"uses online"| node_demo
node_server -->|"initializes"| node_world
node_server -->|"initializes"| node_brain
node_server -->|"initializes"| node_physics
node_world -->|"provides senses"| node_brain
node_brain -->|"modulates drive"| node_vnc
node_vnc -->|"drives actuators"| node_physics
node_physics -->|"returns pose"| node_world
node_world -->|"returns contact"| node_brain
node_brain -->|"loads network"| node_topology
node_brain -->|"searches identities"| node_neurons
node_physics -->|"uses targets"| node_calibration

click node_browser "https://github.com/chenyvhang/cyber-larva/blob/main/web/main.js"
click node_demo "https://github.com/chenyvhang/cyber-larva/blob/main/web/demo-api.js"
click node_server "https://github.com/chenyvhang/cyber-larva/blob/main/server.py"
click node_world "https://github.com/chenyvhang/cyber-larva/blob/main/cyberlarva/world.py"
click node_brain "https://github.com/chenyvhang/cyber-larva/blob/main/cyberlarva/connectome.py"
click node_vnc "https://github.com/chenyvhang/cyber-larva/blob/main/cyberlarva/physics.py"
click node_physics "https://github.com/chenyvhang/cyber-larva/blob/main/cyberlarva/physics.py"
click node_topology "https://github.com/chenyvhang/cyber-larva/tree/main/data/connectome"
click node_calibration "https://github.com/chenyvhang/cyber-larva/blob/main/config/trajectory_calibration.json"
click node_neurons "https://github.com/chenyvhang/cyber-larva/tree/main/data/connectome"

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_browser,node_demo,node_server toneBlue
class node_world toneAmber
class node_brain,node_vnc toneMint
class node_physics toneRose
class node_topology,node_calibration,node_neurons,node_user toneIndigo
```

## Components

### User interface

- [3D interface](https://github.com/chenyvhang/cyber-larva/blob/main/web/main.js): `web/main.js`
- [Browser demo API](https://github.com/chenyvhang/cyber-larva/blob/main/web/demo-api.js): `web/demo-api.js`
- [Local API and loop](https://github.com/chenyvhang/cyber-larva/blob/main/server.py): `server.py`

### Habitat and sensing

- [Habitat and senses](https://github.com/chenyvhang/cyber-larva/blob/main/cyberlarva/world.py): `cyberlarva/world.py`

### Neural and motor control

- [Sparse neural network](https://github.com/chenyvhang/cyber-larva/blob/main/cyberlarva/connectome.py): `cyberlarva/connectome.py`
- [Segmental motor control](https://github.com/chenyvhang/cyber-larva/blob/main/cyberlarva/physics.py): `cyberlarva/physics.py`

### Body simulation

- [MuJoCo body physics](https://github.com/chenyvhang/cyber-larva/blob/main/cyberlarva/physics.py): `cyberlarva/physics.py`

### Scientific data

- [Connectome topology](https://github.com/chenyvhang/cyber-larva/tree/main/data/connectome): `data/connectome`
- [Trajectory calibration](https://github.com/chenyvhang/cyber-larva/blob/main/config/trajectory_calibration.json): `config/trajectory_calibration.json`
- [Neuron identities](https://github.com/chenyvhang/cyber-larva/tree/main/data/connectome): `data/connectome`

### Other components

- **Experimenter**

## Connections

- Experimenter → 3D interface: interacts (evidence: `README.md`)
- 3D interface → Local API and loop: requests state
- 3D interface → Browser demo API: uses online (evidence: `README.md`)
- Local API and loop → Habitat and senses: initializes (evidence: `server.py`)
- Local API and loop → Sparse neural network: initializes (evidence: `server.py`)
- Local API and loop → MuJoCo body physics: initializes (evidence: `server.py`)
- Habitat and senses → Sparse neural network: provides senses (evidence: `README.md`)
- Sparse neural network → Segmental motor control: modulates drive (evidence: `README.md`)
- Segmental motor control → MuJoCo body physics: drives actuators (evidence: `README.md`)
- MuJoCo body physics → Habitat and senses: returns pose (evidence: `README.md`)
- Habitat and senses → Sparse neural network: returns contact (evidence: `README.md`)
- Sparse neural network → Connectome topology: loads network (evidence: `README.md`)
- Sparse neural network → Neuron identities: searches identities (evidence: `README.md`)
- MuJoCo body physics → Trajectory calibration: uses targets (evidence: `README.md`)
