# fruitflydev/therealfly architecture

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

- Interactive diagram: https://gitdiagram.com/fruitflydev/therealfly
- Repository: https://github.com/fruitflydev/therealfly

## Overview

therealfly maps measured connectome annotations to motor-neuron pools, tests cord dynamics, and then translates neural activity into MuJoCo body motion; its closed-loop stage maps body state back to proprioceptor drive. The main user workflow is staged scientific evaluation: map, simulate and assess the cord, run open-loop body trials, then close the sensory loop. The graph includes the documented v2 cord protocol, reflex analysis, and body rendering. Several implementations were not sampled, so their documented capabilities are shown without speculative internal wiring.

Main entry points: [`body/mujoco_body.py`](https://github.com/fruitflydev/therealfly/blob/main/body/mujoco_body.py) (MuJoCo body), [`cord/rhythm.py`](https://github.com/fruitflydev/therealfly/blob/main/cord/rhythm.py) (Rhythm protocol), [`body/openloop.py`](https://github.com/fruitflydev/therealfly/blob/main/body/openloop.py) (Open-loop trials), [`cord/rhythm_v2.py`](https://github.com/fruitflydev/therealfly/blob/main/cord/rhythm_v2.py) (Protocol v2)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mapping["Connectome mapping"]
  node_annotations[("Connectome data<br/>[data.py]")]
  node_motor_map["Motor map<br/>[motor_map.py]"]
end

subgraph group_cord["Cord simulation"]
  node_brain_sim["LIF simulator"]
  node_rhythm["Rhythm protocol<br/>[rhythm.py]"]
  node_props["Brain properties<br/>[brain_props.py]"]
  node_rhythm_v2["Protocol v2<br/>[rhythm_v2.py]"]
end

subgraph group_body["Body and feedback"]
  node_mujoco["MuJoCo fly"]
  node_body_model["Body model<br/>[model.py]"]
  node_body_sim["MuJoCo body<br/>[mujoco_body.py]"]
  node_actuators["Actuator inventory<br/>[actuators.json]"]
  node_signs["Actuator signs<br/>[signs.py]"]
  node_coupling["Motor coupling<br/>[coupling.py]"]
  node_openloop["Open-loop trials<br/>[openloop.py]"]
  node_proprio["Proprioceptor drive<br/>[proprioception.py]"]
  node_render["Body rendering<br/>[render.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_reflex["Reflex analysis<br/>[reflex.py]"]
  node_results["Stage results"]
end

node_researcher(("Researcher"))

node_researcher -->|"builds map"| node_motor_map
node_annotations -->|"reads annotations"| node_motor_map
node_annotations -->|"provides graph data"| node_rhythm
node_researcher -->|"runs protocol"| node_rhythm
node_rhythm -->|"simulates cord"| node_brain_sim
node_rhythm_v2 -->|"reuses simulation"| node_rhythm
node_rhythm_v2 -->|"tests properties"| node_props
node_props -->|"extends model"| node_brain_sim
node_researcher -->|"runs protocol"| node_rhythm_v2
node_motor_map -->|"supplies pools"| node_coupling
node_actuators -->|"defines actuators"| node_coupling
node_signs -->|"supplies signs"| node_coupling
node_body_model -->|"configures body"| node_body_sim
node_body_sim -->|"steps simulation"| node_mujoco
node_researcher -->|"runs trials"| node_openloop
node_openloop -->|"converts rates"| node_coupling
node_openloop -->|"steps body"| node_body_sim
node_openloop -->|"records metrics"| node_results
node_body_sim -->|"provides state"| node_proprio
node_proprio -->|"drives sensory neurons"| node_brain_sim
node_researcher -->|"evaluates reflex"| node_reflex
node_reflex -->|"analyzes wiring"| node_brain_sim
node_body_sim -.->|"provides body state"| node_render
node_rhythm -->|"writes metrics"| node_results
node_rhythm_v2 -->|"writes metrics"| node_results

click node_annotations "https://github.com/fruitflydev/therealfly/blob/main/therealfly/data.py"
click node_motor_map "https://github.com/fruitflydev/therealfly/blob/main/therealfly/motor_map.py"
click node_rhythm "https://github.com/fruitflydev/therealfly/blob/main/cord/rhythm.py"
click node_props "https://github.com/fruitflydev/therealfly/blob/main/cord/brain_props.py"
click node_rhythm_v2 "https://github.com/fruitflydev/therealfly/blob/main/cord/rhythm_v2.py"
click node_body_model "https://github.com/fruitflydev/therealfly/blob/main/body/model.py"
click node_body_sim "https://github.com/fruitflydev/therealfly/blob/main/body/mujoco_body.py"
click node_actuators "https://github.com/fruitflydev/therealfly/blob/main/body/actuators.json"
click node_signs "https://github.com/fruitflydev/therealfly/blob/main/body/signs.py"
click node_coupling "https://github.com/fruitflydev/therealfly/blob/main/body/coupling.py"
click node_openloop "https://github.com/fruitflydev/therealfly/blob/main/body/openloop.py"
click node_proprio "https://github.com/fruitflydev/therealfly/blob/main/body/proprioception.py"
click node_reflex "https://github.com/fruitflydev/therealfly/blob/main/body/reflex.py"
click node_render "https://github.com/fruitflydev/therealfly/blob/main/body/render.py"
click node_results "https://github.com/fruitflydev/therealfly/tree/main/build"

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_annotations,node_motor_map toneBlue
class node_brain_sim,node_rhythm,node_props,node_rhythm_v2 toneAmber
class node_mujoco,node_body_model,node_body_sim,node_actuators,node_signs,node_coupling,node_openloop,node_proprio,node_render toneMint
class node_reflex,node_results toneRose
class node_researcher toneIndigo
```

## Components

### Connectome mapping

- [Connectome data](https://github.com/fruitflydev/therealfly/blob/main/therealfly/data.py): `therealfly/data.py`
- [Motor map](https://github.com/fruitflydev/therealfly/blob/main/therealfly/motor_map.py): `therealfly/motor_map.py`

### Cord simulation

- **LIF simulator**
- [Rhythm protocol](https://github.com/fruitflydev/therealfly/blob/main/cord/rhythm.py): `cord/rhythm.py`
- [Brain properties](https://github.com/fruitflydev/therealfly/blob/main/cord/brain_props.py): `cord/brain_props.py`
- [Protocol v2](https://github.com/fruitflydev/therealfly/blob/main/cord/rhythm_v2.py): `cord/rhythm_v2.py`

### Body and feedback

- **MuJoCo fly**
- [Body model](https://github.com/fruitflydev/therealfly/blob/main/body/model.py): `body/model.py`
- [MuJoCo body](https://github.com/fruitflydev/therealfly/blob/main/body/mujoco_body.py): `body/mujoco_body.py`
- [Actuator inventory](https://github.com/fruitflydev/therealfly/blob/main/body/actuators.json): `body/actuators.json`
- [Actuator signs](https://github.com/fruitflydev/therealfly/blob/main/body/signs.py): `body/signs.py`
- [Motor coupling](https://github.com/fruitflydev/therealfly/blob/main/body/coupling.py): `body/coupling.py`
- [Open-loop trials](https://github.com/fruitflydev/therealfly/blob/main/body/openloop.py): `body/openloop.py`
- [Proprioceptor drive](https://github.com/fruitflydev/therealfly/blob/main/body/proprioception.py): `body/proprioception.py`
- [Body rendering](https://github.com/fruitflydev/therealfly/blob/main/body/render.py): `body/render.py`

### Evaluation

- [Reflex analysis](https://github.com/fruitflydev/therealfly/blob/main/body/reflex.py): `body/reflex.py`
- [Stage results](https://github.com/fruitflydev/therealfly/tree/main/build): `build`

### Other components

- **Researcher**

## Connections

- Researcher → Motor map: builds map
- Connectome data → Motor map: reads annotations
- Connectome data → Rhythm protocol: provides graph data
- Researcher → Rhythm protocol: runs protocol
- Rhythm protocol → LIF simulator: simulates cord
- Protocol v2 → Rhythm protocol: reuses simulation
- Protocol v2 → Brain properties: tests properties
- Brain properties → LIF simulator: extends model
- Researcher → Protocol v2: runs protocol
- Motor map → Motor coupling: supplies pools
- Actuator inventory → Motor coupling: defines actuators
- Actuator signs → Motor coupling: supplies signs
- Body model → MuJoCo body: configures body
- MuJoCo body → MuJoCo fly: steps simulation
- Researcher → Open-loop trials: runs trials
- Open-loop trials → Motor coupling: converts rates
- Open-loop trials → MuJoCo body: steps body
- Open-loop trials → Stage results: records metrics
- MuJoCo body → Proprioceptor drive: provides state
- Proprioceptor drive → LIF simulator: drives sensory neurons
- Researcher → Reflex analysis: evaluates reflex
- Reflex analysis → LIF simulator: analyzes wiring
- MuJoCo body → Body rendering: provides body state
- Rhythm protocol → Stage results: writes metrics
- Protocol v2 → Stage results: writes metrics