# shadowc707/chong-fly architecture

> Architecture diagram of the GitHub repository shadowc707/chong-fly, 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/shadowc707/chong-fly
- Repository: https://github.com/shadowc707/chong-fly

## Overview

Chong Fly builds biologically grounded drone autopilots from a Drosophila connectome, then evaluates and targets them for flight. The primary workflow extracts or synthesizes circuit topology, reduces it into deployable matrices, constructs a CfC policy, and closes the loop through simulated sensors, flight dynamics, and PWM control. Optimization and edge export are supporting branches. The README documents broader circuit and deployment capabilities; some implementations were not sampled, so uncertain wiring is omitted.

Main entry points: [`simulation/drone_env.py`](https://github.com/shadowc707/chong-fly/blob/main/simulation/drone_env.py) (Drone environment), [`simulation/policy.py`](https://github.com/shadowc707/chong-fly/blob/main/simulation/policy.py) (Sensor-to-PWM policy), [`optimizer/evaluate.py`](https://github.com/shadowc707/chong-fly/blob/main/optimizer/evaluate.py) (Behavior evaluator), [`generator/circuit_extractor.py`](https://github.com/shadowc707/chong-fly/blob/main/generator/circuit_extractor.py) (Circuit extraction)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_circuit["Circuit modeling"]
  node_extract["Circuit extraction"]
  node_mapping["Cell mapping<br/>[cell_mapping.json]"]
  node_raw[("Connectome topology")]
  node_reduce["Graph reduction<br/>[graph_reducer.py]"]
  node_models[("Reduced matrices")]
end

subgraph group_autopilot["Neural autopilot"]
  node_cfc["Biological CfC core<br/>[models.py]"]
  node_policy["Sensor-to-PWM policy<br/>[policy.py]"]
end

subgraph group_flight["Flight simulation"]
  node_flow["Optical flow sensor"]
  node_env["Drone environment<br/>[drone_env.py]"]
  node_avionics["PID flight control<br/>[avionics_filter.py]"]
  node_interface["Drone interface<br/>[drone_interface.py]"]
  node_memory["Flight memory<br/>[memory.py]"]
  node_metrics["Flight metrics<br/>[metrics.py]"]
  node_hud["Simulation HUD<br/>[isaac_hud.py]"]
end

subgraph group_tuning["Optimization"]
  node_evaluate["Behavior evaluator<br/>[evaluate.py]"]
  node_cma["CMA-ES tuner<br/>[cma_es_tuner.py]"]
  node_optuna["Optuna tuner<br/>[optuna_tuner.py]"]
  node_pretrain["Policy pretraining<br/>[pretrain.py]"]
end

subgraph group_deployment["Edge deployment"]
  node_onnx["ONNX exporter<br/>[export_onnx.py]"]
  node_quantizer["Model quantizer<br/>[quantizer.py]"]
  node_codegen["C code generator<br/>[codegen_c.py]"]
  node_embedded["Embedded runtimes"]
end

node_user(("Engineer / operator"))
node_cave(("FlyWire CAVE"))

node_user -->|"starts extraction"| node_extract
node_extract -->|"reads config"| node_mapping
node_extract -->|"writes topology"| node_raw
node_cave -.->|"supplies connectome"| node_extract
node_user -->|"runs reduction"| node_reduce
node_reduce -->|"reads topology"| node_raw
node_reduce -->|"writes matrices"| node_models
node_user -->|"selects policy"| node_policy
node_policy -->|"loads model metadata"| node_models
node_policy -->|"runs neural core"| node_cfc
node_flow -->|"provides flow"| node_policy
node_env -->|"provides flight state"| node_flow
node_policy -->|"sends PWM"| node_env
node_env -->|"uses flight control"| node_avionics
node_env -->|"exposes drone interface"| node_interface
node_env -->|"records state"| node_memory
node_env -->|"reports outcomes"| node_metrics
node_env -->|"renders simulation"| node_hud
node_user -->|"requests evaluation"| node_evaluate
node_evaluate -->|"evaluates in simulation"| node_env
node_evaluate -->|"runs policy"| node_policy
node_cma -->|"scores candidates"| node_evaluate
node_optuna -->|"scores trials"| node_evaluate
node_pretrain -.->|"trains policy"| node_policy
node_user -.->|"exports model"| node_onnx
node_user -.->|"quantizes model"| node_quantizer
node_user -.->|"generates C"| node_codegen
node_onnx -.->|"targets runtime"| node_embedded
node_codegen -.->|"targets runtime"| node_embedded

click node_extract "https://github.com/shadowc707/chong-fly/blob/main/generator/circuit_extractor.py"
click node_mapping "https://github.com/shadowc707/chong-fly/blob/main/configs/cell_mapping.json"
click node_raw "https://github.com/shadowc707/chong-fly/tree/main/data/raw_connectome"
click node_reduce "https://github.com/shadowc707/chong-fly/blob/main/generator/graph_reducer.py"
click node_models "https://github.com/shadowc707/chong-fly/tree/main/data/reduced_models"
click node_cfc "https://github.com/shadowc707/chong-fly/blob/main/core/models.py"
click node_policy "https://github.com/shadowc707/chong-fly/blob/main/simulation/policy.py"
click node_flow "https://github.com/shadowc707/chong-fly/blob/main/simulation/pmw3901_emulator.py"
click node_env "https://github.com/shadowc707/chong-fly/blob/main/simulation/drone_env.py"
click node_avionics "https://github.com/shadowc707/chong-fly/blob/main/simulation/avionics_filter.py"
click node_interface "https://github.com/shadowc707/chong-fly/blob/main/simulation/drone_interface.py"
click node_memory "https://github.com/shadowc707/chong-fly/blob/main/simulation/memory.py"
click node_metrics "https://github.com/shadowc707/chong-fly/blob/main/simulation/metrics.py"
click node_hud "https://github.com/shadowc707/chong-fly/blob/main/simulation/isaac_hud.py"
click node_evaluate "https://github.com/shadowc707/chong-fly/blob/main/optimizer/evaluate.py"
click node_cma "https://github.com/shadowc707/chong-fly/blob/main/optimizer/cma_es_tuner.py"
click node_optuna "https://github.com/shadowc707/chong-fly/blob/main/optimizer/optuna_tuner.py"
click node_pretrain "https://github.com/shadowc707/chong-fly/blob/main/optimizer/pretrain.py"
click node_onnx "https://github.com/shadowc707/chong-fly/blob/main/edge/exporter/export_onnx.py"
click node_quantizer "https://github.com/shadowc707/chong-fly/blob/main/edge/exporter/quantizer.py"
click node_codegen "https://github.com/shadowc707/chong-fly/blob/main/edge/exporter/codegen_c.py"
click node_embedded "https://github.com/shadowc707/chong-fly/tree/main/edge/embedded"

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_extract,node_mapping,node_raw,node_reduce,node_models toneBlue
class node_cfc,node_policy toneAmber
class node_flow,node_env,node_avionics,node_interface,node_memory,node_metrics,node_hud toneMint
class node_evaluate,node_cma,node_optuna,node_pretrain toneRose
class node_onnx,node_quantizer,node_codegen,node_embedded,node_user,node_cave toneIndigo
```

## Components

### Circuit modeling

- [Circuit extraction](https://github.com/shadowc707/chong-fly/blob/main/generator/circuit_extractor.py): `generator/circuit_extractor.py`
- [Cell mapping](https://github.com/shadowc707/chong-fly/blob/main/configs/cell_mapping.json): `configs/cell_mapping.json`
- [Connectome topology](https://github.com/shadowc707/chong-fly/tree/main/data/raw_connectome): `data/raw_connectome`
- [Graph reduction](https://github.com/shadowc707/chong-fly/blob/main/generator/graph_reducer.py): `generator/graph_reducer.py`
- [Reduced matrices](https://github.com/shadowc707/chong-fly/tree/main/data/reduced_models): `data/reduced_models`

### Neural autopilot

- [Biological CfC core](https://github.com/shadowc707/chong-fly/blob/main/core/models.py): `core/models.py`
- [Sensor-to-PWM policy](https://github.com/shadowc707/chong-fly/blob/main/simulation/policy.py): `simulation/policy.py`

### Flight simulation

- [Optical flow sensor](https://github.com/shadowc707/chong-fly/blob/main/simulation/pmw3901_emulator.py): `simulation/pmw3901_emulator.py`
- [Drone environment](https://github.com/shadowc707/chong-fly/blob/main/simulation/drone_env.py): `simulation/drone_env.py`
- [PID flight control](https://github.com/shadowc707/chong-fly/blob/main/simulation/avionics_filter.py): `simulation/avionics_filter.py`
- [Drone interface](https://github.com/shadowc707/chong-fly/blob/main/simulation/drone_interface.py): `simulation/drone_interface.py`
- [Flight memory](https://github.com/shadowc707/chong-fly/blob/main/simulation/memory.py): `simulation/memory.py`
- [Flight metrics](https://github.com/shadowc707/chong-fly/blob/main/simulation/metrics.py): `simulation/metrics.py`
- [Simulation HUD](https://github.com/shadowc707/chong-fly/blob/main/simulation/isaac_hud.py): `simulation/isaac_hud.py`

### Optimization

- [Behavior evaluator](https://github.com/shadowc707/chong-fly/blob/main/optimizer/evaluate.py): `optimizer/evaluate.py`
- [CMA-ES tuner](https://github.com/shadowc707/chong-fly/blob/main/optimizer/cma_es_tuner.py): `optimizer/cma_es_tuner.py`
- [Optuna tuner](https://github.com/shadowc707/chong-fly/blob/main/optimizer/optuna_tuner.py): `optimizer/optuna_tuner.py`
- [Policy pretraining](https://github.com/shadowc707/chong-fly/blob/main/optimizer/pretrain.py): `optimizer/pretrain.py`

### Edge deployment

- [ONNX exporter](https://github.com/shadowc707/chong-fly/blob/main/edge/exporter/export_onnx.py): `edge/exporter/export_onnx.py`
- [Model quantizer](https://github.com/shadowc707/chong-fly/blob/main/edge/exporter/quantizer.py): `edge/exporter/quantizer.py`
- [C code generator](https://github.com/shadowc707/chong-fly/blob/main/edge/exporter/codegen_c.py): `edge/exporter/codegen_c.py`
- [Embedded runtimes](https://github.com/shadowc707/chong-fly/tree/main/edge/embedded): `edge/embedded`

### Other components

- **Engineer / operator**
- **FlyWire CAVE**

## Connections

- Engineer / operator → Circuit extraction: starts extraction
- Circuit extraction → Cell mapping: reads config
- Circuit extraction → Connectome topology: writes topology
- FlyWire CAVE → Circuit extraction: supplies connectome
- Engineer / operator → Graph reduction: runs reduction
- Graph reduction → Connectome topology: reads topology
- Graph reduction → Reduced matrices: writes matrices
- Engineer / operator → Sensor-to-PWM policy: selects policy
- Sensor-to-PWM policy → Reduced matrices: loads model metadata
- Sensor-to-PWM policy → Biological CfC core: runs neural core
- Optical flow sensor → Sensor-to-PWM policy: provides flow
- Drone environment → Optical flow sensor: provides flight state
- Sensor-to-PWM policy → Drone environment: sends PWM
- Drone environment → PID flight control: uses flight control
- Drone environment → Drone interface: exposes drone interface
- Drone environment → Flight memory: records state
- Drone environment → Flight metrics: reports outcomes
- Drone environment → Simulation HUD: renders simulation
- Engineer / operator → Behavior evaluator: requests evaluation
- Behavior evaluator → Drone environment: evaluates in simulation
- Behavior evaluator → Sensor-to-PWM policy: runs policy
- CMA-ES tuner → Behavior evaluator: scores candidates
- Optuna tuner → Behavior evaluator: scores trials
- Policy pretraining → Sensor-to-PWM policy: trains policy
- Engineer / operator → ONNX exporter: exports model
- Engineer / operator → Model quantizer: quantizes model
- Engineer / operator → C code generator: generates C
- ONNX exporter → Embedded runtimes: targets runtime
- C code generator → Embedded runtimes: targets runtime