# hotocoo/malecns architecture

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

- Interactive diagram: https://gitdiagram.com/hotocoo/malecns
- Repository: https://github.com/hotocoo/malecns

## Overview

malecns trains a fixed MaleCNS connectome to drive a simulated car around Monaco. The main workflow feeds road sensing into the fly-brain interface, simulates spiking activity, reads descending-neuron activity into controls, and evolves interface parameters with headless training. Separate branches prepare connectome and circuit data, model road law and visual perception, evaluate trained policies, and stream live runs to a browser. Some subsystem links are documented in the README; source excerpts and the index provide only partial implementation evidence, so uncertain wiring is omitted.

Main entry points: [`src/train.py`](https://github.com/hotocoo/malecns/blob/main/src/train.py) (ES Trainer), [`web/app.js`](https://github.com/hotocoo/malecns/blob/main/web/app.js) (Browser UI), [`src/brain.py`](https://github.com/hotocoo/malecns/blob/main/src/brain.py) (LIF Brain), [`src/agent.py`](https://github.com/hotocoo/malecns/blob/main/src/agent.py) (Fly Agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Connectome Data"]
  node_connectome_data["Connectome Data<br/>[download.py]"]
  node_graph_builder["Graph Builder<br/>[build_graph.py]"]
end

subgraph group_world["Circuit World"]
  node_circuit_law["Road Law<br/>[roadlaw.py]"]
  node_law_reward["Law Reward<br/>[lawreward.py]"]
  node_scene["Circuit Scene<br/>[scene.py]"]
  node_camera["Rendered Camera<br/>[camera.py]"]
  node_perception["Visual Perception<br/>[perceive.py]"]
  node_eye_camera["Eye Camera<br/>[eye_camera.py]"]
  node_dataset["Perception Dataset<br/>[dataset.py]"]
  node_terrain["Terrain Model<br/>[terrain.py]"]
  node_scenery_fetch["Scenery Fetch<br/>[fetch_scenery.py]"]
end

subgraph group_runtime["Driving Runtime"]
  node_brain["LIF Brain<br/>[brain.py]"]
  node_metal_kernel["Metal LIF Kernel<br/>[metal_lif.py]"]
  node_agent["Fly Agent<br/>[agent.py]"]
  node_car_env["Car Environment<br/>[car_env.py]"]
end

subgraph group_learning["Training &amp; Evaluation"]
  node_trainer["ES Trainer<br/>[train.py]"]
  node_evaluator["Policy Evaluation<br/>[evaluate.py]"]
  node_exploit_monitor["Reward Exploit Scan<br/>[exploits.py]"]
  node_calibrator["Motor Calibration<br/>[calibrate.py]"]
  node_teacher["Driving Teacher<br/>[teacher.py]"]
end

subgraph group_watch["Live Viewer"]
  node_viewer["Viewer Server<br/>[viewer.py]"]
  node_browser["Browser UI<br/>[app.js]"]
  node_browser_brain["Brain Visualizer<br/>[brain.js]"]
  node_browser_drive["Driving View<br/>[drive.js]"]
  node_browser_firstperson["Cockpit View<br/>[firstperson.js]"]
  node_browser_scenery["Scenery Renderer<br/>[scenery.js]"]
end

node_operator(("Operator"))

node_operator -->|"downloads"| node_connectome_data
node_connectome_data -->|"builds graph"| node_graph_builder
node_graph_builder -->|"supplies connectome"| node_brain
node_agent -->|"drives"| node_brain
node_brain -->|"dispatches on Apple GPU"| node_metal_kernel
node_trainer -->|"optimizes interface"| node_agent
node_trainer -->|"loads connectome"| node_brain
node_trainer -->|"runs rollouts"| node_car_env
node_trainer -->|"monitors reward"| node_exploit_monitor
node_trainer -->|"evaluates policy"| node_evaluator
node_calibrator -->|"fits readout"| node_agent
node_calibrator -->|"uses demonstrations"| node_teacher
node_calibrator -->|"simulates driving"| node_car_env
node_evaluator -->|"loads checkpoint"| node_agent
node_evaluator -->|"runs scenarios"| node_car_env
node_evaluator -->|"checks exploits"| node_exploit_monitor
node_car_env -->|"uses elevation"| node_terrain
node_scene -->|"uses road rules"| node_circuit_law
node_law_reward -->|"charges violations"| node_circuit_law
node_camera -->|"renders geometry"| node_scene
node_eye_camera -->|"captures frames"| node_camera
node_eye_camera -->|"processes vision"| node_perception
node_dataset -->|"renders samples"| node_camera
node_dataset -->|"uses detections"| node_perception
node_operator -.->|"fetches optional scenery"| node_scenery_fetch
node_viewer -->|"runs checkpoint"| node_agent
node_viewer -->|"loads connectome"| node_brain
node_viewer -->|"simulates live car"| node_car_env
node_viewer -->|"streams frames"| node_browser
node_browser -->|"shows brain"| node_browser_brain
node_browser -->|"shows circuit"| node_browser_drive
node_browser -->|"offers cockpit"| node_browser_firstperson
node_browser -->|"renders scenery"| node_browser_scenery

click node_connectome_data "https://github.com/hotocoo/malecns/blob/main/src/download.py"
click node_graph_builder "https://github.com/hotocoo/malecns/blob/main/src/build_graph.py"
click node_brain "https://github.com/hotocoo/malecns/blob/main/src/brain.py"
click node_metal_kernel "https://github.com/hotocoo/malecns/blob/main/src/metal_lif.py"
click node_agent "https://github.com/hotocoo/malecns/blob/main/src/agent.py"
click node_car_env "https://github.com/hotocoo/malecns/blob/main/src/car_env.py"
click node_trainer "https://github.com/hotocoo/malecns/blob/main/src/train.py"
click node_evaluator "https://github.com/hotocoo/malecns/blob/main/src/evaluate.py"
click node_exploit_monitor "https://github.com/hotocoo/malecns/blob/main/src/exploits.py"
click node_calibrator "https://github.com/hotocoo/malecns/blob/main/src/calibrate.py"
click node_teacher "https://github.com/hotocoo/malecns/blob/main/src/teacher.py"
click node_circuit_law "https://github.com/hotocoo/malecns/blob/main/src/roadlaw.py"
click node_law_reward "https://github.com/hotocoo/malecns/blob/main/src/lawreward.py"
click node_scene "https://github.com/hotocoo/malecns/blob/main/src/scene.py"
click node_camera "https://github.com/hotocoo/malecns/blob/main/src/camera.py"
click node_perception "https://github.com/hotocoo/malecns/blob/main/src/perceive.py"
click node_eye_camera "https://github.com/hotocoo/malecns/blob/main/src/eye_camera.py"
click node_dataset "https://github.com/hotocoo/malecns/blob/main/src/dataset.py"
click node_terrain "https://github.com/hotocoo/malecns/blob/main/src/terrain.py"
click node_scenery_fetch "https://github.com/hotocoo/malecns/blob/main/src/fetch_scenery.py"
click node_viewer "https://github.com/hotocoo/malecns/blob/main/src/viewer.py"
click node_browser "https://github.com/hotocoo/malecns/blob/main/web/app.js"
click node_browser_brain "https://github.com/hotocoo/malecns/blob/main/web/brain.js"
click node_browser_drive "https://github.com/hotocoo/malecns/blob/main/web/drive.js"
click node_browser_firstperson "https://github.com/hotocoo/malecns/blob/main/web/firstperson.js"
click node_browser_scenery "https://github.com/hotocoo/malecns/blob/main/web/scenery.js"

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_connectome_data,node_graph_builder toneBlue
class node_circuit_law,node_law_reward,node_scene,node_camera,node_perception,node_eye_camera,node_dataset,node_terrain,node_scenery_fetch toneAmber
class node_brain,node_metal_kernel,node_agent,node_car_env toneMint
class node_trainer,node_evaluator,node_exploit_monitor,node_calibrator,node_teacher toneRose
class node_viewer,node_browser,node_browser_brain,node_browser_drive,node_browser_firstperson,node_browser_scenery,node_operator toneIndigo
```

## Components

### Connectome Data

- [Connectome Data](https://github.com/hotocoo/malecns/blob/main/src/download.py): `src/download.py`
- [Graph Builder](https://github.com/hotocoo/malecns/blob/main/src/build_graph.py): `src/build_graph.py`

### Circuit World

- [Road Law](https://github.com/hotocoo/malecns/blob/main/src/roadlaw.py): `src/roadlaw.py`
- [Law Reward](https://github.com/hotocoo/malecns/blob/main/src/lawreward.py): `src/lawreward.py`
- [Circuit Scene](https://github.com/hotocoo/malecns/blob/main/src/scene.py): `src/scene.py`
- [Rendered Camera](https://github.com/hotocoo/malecns/blob/main/src/camera.py): `src/camera.py`
- [Visual Perception](https://github.com/hotocoo/malecns/blob/main/src/perceive.py): `src/perceive.py`
- [Eye Camera](https://github.com/hotocoo/malecns/blob/main/src/eye_camera.py): `src/eye_camera.py`
- [Perception Dataset](https://github.com/hotocoo/malecns/blob/main/src/dataset.py): `src/dataset.py`
- [Terrain Model](https://github.com/hotocoo/malecns/blob/main/src/terrain.py): `src/terrain.py`
- [Scenery Fetch](https://github.com/hotocoo/malecns/blob/main/src/fetch_scenery.py): `src/fetch_scenery.py`

### Driving Runtime

- [LIF Brain](https://github.com/hotocoo/malecns/blob/main/src/brain.py): `src/brain.py`
- [Metal LIF Kernel](https://github.com/hotocoo/malecns/blob/main/src/metal_lif.py): `src/metal_lif.py`
- [Fly Agent](https://github.com/hotocoo/malecns/blob/main/src/agent.py): `src/agent.py`
- [Car Environment](https://github.com/hotocoo/malecns/blob/main/src/car_env.py): `src/car_env.py`

### Training & Evaluation

- [ES Trainer](https://github.com/hotocoo/malecns/blob/main/src/train.py): `src/train.py`
- [Policy Evaluation](https://github.com/hotocoo/malecns/blob/main/src/evaluate.py): `src/evaluate.py`
- [Reward Exploit Scan](https://github.com/hotocoo/malecns/blob/main/src/exploits.py): `src/exploits.py`
- [Motor Calibration](https://github.com/hotocoo/malecns/blob/main/src/calibrate.py): `src/calibrate.py`
- [Driving Teacher](https://github.com/hotocoo/malecns/blob/main/src/teacher.py): `src/teacher.py`

### Live Viewer

- [Viewer Server](https://github.com/hotocoo/malecns/blob/main/src/viewer.py): `src/viewer.py`
- [Browser UI](https://github.com/hotocoo/malecns/blob/main/web/app.js): `web/app.js`
- [Brain Visualizer](https://github.com/hotocoo/malecns/blob/main/web/brain.js): `web/brain.js`
- [Driving View](https://github.com/hotocoo/malecns/blob/main/web/drive.js): `web/drive.js`
- [Cockpit View](https://github.com/hotocoo/malecns/blob/main/web/firstperson.js): `web/firstperson.js`
- [Scenery Renderer](https://github.com/hotocoo/malecns/blob/main/web/scenery.js): `web/scenery.js`

### Other components

- **Operator**

## Connections

- Operator → Connectome Data: downloads
- Connectome Data → Graph Builder: builds graph
- Graph Builder → LIF Brain: supplies connectome
- Fly Agent → LIF Brain: drives (evidence: `src/agent.py`)
- LIF Brain → Metal LIF Kernel: dispatches on Apple GPU (evidence: `src/brain.py`)
- ES Trainer → Fly Agent: optimizes interface (evidence: `src/train.py`)
- ES Trainer → LIF Brain: loads connectome (evidence: `src/train.py`)
- ES Trainer → Car Environment: runs rollouts (evidence: `src/train.py`)
- ES Trainer → Reward Exploit Scan: monitors reward (evidence: `src/train.py`)
- ES Trainer → Policy Evaluation: evaluates policy (evidence: `src/train.py`)
- Motor Calibration → Fly Agent: fits readout (evidence: `src/calibrate.py`)
- Motor Calibration → Driving Teacher: uses demonstrations (evidence: `src/calibrate.py`)
- Motor Calibration → Car Environment: simulates driving (evidence: `src/calibrate.py`)
- Policy Evaluation → Fly Agent: loads checkpoint (evidence: `src/evaluate.py`)
- Policy Evaluation → Car Environment: runs scenarios (evidence: `src/evaluate.py`)
- Policy Evaluation → Reward Exploit Scan: checks exploits (evidence: `src/evaluate.py`)
- Car Environment → Terrain Model: uses elevation (evidence: `src/car_env.py`)
- Circuit Scene → Road Law: uses road rules (evidence: `src/scene.py`)
- Law Reward → Road Law: charges violations (evidence: `src/lawreward.py`)
- Rendered Camera → Circuit Scene: renders geometry (evidence: `src/camera.py`)
- Eye Camera → Rendered Camera: captures frames (evidence: `src/eye_camera.py`)
- Eye Camera → Visual Perception: processes vision (evidence: `src/eye_camera.py`)
- Perception Dataset → Rendered Camera: renders samples (evidence: `src/dataset.py`)
- Perception Dataset → Visual Perception: uses detections (evidence: `src/dataset.py`)
- Operator → Scenery Fetch: fetches optional scenery
- Viewer Server → Fly Agent: runs checkpoint (evidence: `src/viewer.py`)
- Viewer Server → LIF Brain: loads connectome (evidence: `src/viewer.py`)
- Viewer Server → Car Environment: simulates live car (evidence: `src/viewer.py`)
- Viewer Server → Browser UI: streams frames
- Browser UI → Brain Visualizer: shows brain
- Browser UI → Driving View: shows circuit
- Browser UI → Cockpit View: offers cockpit
- Browser UI → Scenery Renderer: renders scenery
