# aastik0303/fruit_fly_autodrive architecture

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

- Interactive diagram: https://gitdiagram.com/aastik0303/fruit_fly_autodrive
- Repository: https://github.com/aastik0303/fruit_fly_autodrive

## Overview

NeuroPath AI combines FlyWire connectome ingestion and neuron exploration with an embodied dodge-game demonstration. The explorer workflow runs from the user through the React page and API client to backend routes and connectome tables, then displays neuron data in a 3D scene. The game workflow encodes the falling-block scene as eye input, propagates it through the connectome, and selects actions with a learned Q readout. Edges follow excerpts, SOURCE INDEX references, or README documentation; unsampled route details are not expanded.

Main entry points: [`backend/api/game.py`](https://github.com/aastik0303/fruit_fly_autodrive/blob/main/backend/api/game.py) (Game WebSocket), [`frontend/src/pages/FlyGamePage.jsx`](https://github.com/aastik0303/fruit_fly_autodrive/blob/main/frontend/src/pages/FlyGamePage.jsx) (Game interface), [`backend/embodied/train.py`](https://github.com/aastik0303/fruit_fly_autodrive/blob/main/backend/embodied/train.py) (Agent training), [`backend/embodied/brain.py`](https://github.com/aastik0303/fruit_fly_autodrive/blob/main/backend/embodied/brain.py) (Connectome response)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Connectome data"]
  node_ingest["Data ingestion<br/>[ingest.py]"]
  node_tables[("Processed tables<br/>[loaders.py]")]
  node_loaders["Table loaders<br/>[loaders.py]"]
end

subgraph group_backend["Backend runtime"]
  node_api_main["API app<br/>[main.py]"]
  node_api_store["Neuron API<br/>[store.py]"]
  node_game_socket["Game WebSocket<br/>[game.py]"]
  node_eye["Eye encoding<br/>[eye.py]"]
  node_brain["Connectome response<br/>[brain.py]"]
  node_dodge["Dodge environment<br/>[dodge_env.py]"]
  node_agent["Q-learning agent<br/>[agent.py]"]
  node_trainer["Agent training<br/>[train.py]"]
end

subgraph group_frontend["Connectome explorer"]
  node_app["Frontend app<br/>[App.jsx]"]
  node_explorer["Neuron explorer<br/>[ExplorerPage.jsx]"]
  node_api_client["REST client<br/>[api.js]"]
  node_brain_scene["Connectome scene<br/>[BrainScene.jsx]"]
end

subgraph group_gameui["Embodied game"]
  node_game_page["Game interface<br/>[FlyGamePage.jsx]"]
  node_game_client["Game socket client<br/>[gameSocket.js]"]
  node_arena["Game arena<br/>[GameArena.jsx]"]
  node_activity["Brain activity view<br/>[BrainActivity.jsx]"]
end

node_user(("Researcher"))

node_user -->|"opens"| node_app
node_app -->|"renders"| node_explorer
node_app -->|"renders"| node_game_page
node_ingest -->|"writes"| node_tables
node_loaders -->|"reads"| node_tables
node_api_main -->|"registers"| node_api_store
node_api_main -->|"registers"| node_game_socket
node_api_store -->|"loads"| node_loaders
node_explorer -->|"requests data"| node_api_client
node_api_client -->|"requests neuron data"| node_api_store
node_explorer -->|"renders"| node_brain_scene
node_game_page -->|"connects"| node_game_client
node_game_client -->|"exchanges commands"| node_game_socket
node_game_page -->|"requests point cloud"| node_api_client
node_api_client -->|"requests visualization"| node_api_store
node_game_page -->|"renders"| node_arena
node_game_page -->|"renders"| node_activity
node_game_socket -->|"advances game"| node_dodge
node_game_socket -->|"encodes view"| node_eye
node_game_socket -->|"computes activity"| node_brain
node_game_socket -->|"selects action"| node_agent
node_brain -->|"uses input matrix"| node_eye
node_brain -->|"loads connectome"| node_loaders
node_eye -->|"uses game geometry"| node_dodge
node_trainer -->|"trains against"| node_brain
node_trainer -->|"trains"| node_agent
node_trainer -->|"simulates episodes"| node_dodge
node_trainer -->|"featurizes views"| node_eye
node_arena -.->|"displays alongside"| node_activity

click node_ingest "https://github.com/aastik0303/fruit_fly_autodrive/blob/main/backend/preprocessing/ingest.py"
click node_tables "https://github.com/aastik0303/fruit_fly_autodrive/blob/main/backend/preprocessing/loaders.py"
click node_loaders "https://github.com/aastik0303/fruit_fly_autodrive/blob/main/backend/preprocessing/loaders.py"
click node_api_main "https://github.com/aastik0303/fruit_fly_autodrive/blob/main/backend/api/main.py"
click node_api_store "https://github.com/aastik0303/fruit_fly_autodrive/blob/main/backend/api/store.py"
click node_game_socket "https://github.com/aastik0303/fruit_fly_autodrive/blob/main/backend/api/game.py"
click node_eye "https://github.com/aastik0303/fruit_fly_autodrive/blob/main/backend/embodied/eye.py"
click node_brain "https://github.com/aastik0303/fruit_fly_autodrive/blob/main/backend/embodied/brain.py"
click node_dodge "https://github.com/aastik0303/fruit_fly_autodrive/blob/main/backend/embodied/dodge_env.py"
click node_agent "https://github.com/aastik0303/fruit_fly_autodrive/blob/main/backend/embodied/agent.py"
click node_trainer "https://github.com/aastik0303/fruit_fly_autodrive/blob/main/backend/embodied/train.py"
click node_app "https://github.com/aastik0303/fruit_fly_autodrive/blob/main/frontend/src/App.jsx"
click node_explorer "https://github.com/aastik0303/fruit_fly_autodrive/blob/main/frontend/src/pages/ExplorerPage.jsx"
click node_api_client "https://github.com/aastik0303/fruit_fly_autodrive/blob/main/frontend/src/services/api.js"
click node_brain_scene "https://github.com/aastik0303/fruit_fly_autodrive/blob/main/frontend/src/three/BrainScene.jsx"
click node_game_page "https://github.com/aastik0303/fruit_fly_autodrive/blob/main/frontend/src/pages/FlyGamePage.jsx"
click node_game_client "https://github.com/aastik0303/fruit_fly_autodrive/blob/main/frontend/src/services/gameSocket.js"
click node_arena "https://github.com/aastik0303/fruit_fly_autodrive/blob/main/frontend/src/three/GameArena.jsx"
click node_activity "https://github.com/aastik0303/fruit_fly_autodrive/blob/main/frontend/src/three/BrainActivity.jsx"

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_ingest,node_tables,node_loaders toneBlue
class node_api_main,node_api_store,node_game_socket,node_eye,node_brain,node_dodge,node_agent,node_trainer toneAmber
class node_app,node_explorer,node_api_client,node_brain_scene toneMint
class node_game_page,node_game_client,node_arena,node_activity toneRose
class node_user toneIndigo
```

## Components

### Connectome data

- [Data ingestion](https://github.com/aastik0303/fruit_fly_autodrive/blob/main/backend/preprocessing/ingest.py): `backend/preprocessing/ingest.py`
- [Processed tables](https://github.com/aastik0303/fruit_fly_autodrive/blob/main/backend/preprocessing/loaders.py): `backend/preprocessing/loaders.py`
- [Table loaders](https://github.com/aastik0303/fruit_fly_autodrive/blob/main/backend/preprocessing/loaders.py): `backend/preprocessing/loaders.py`

### Backend runtime

- [API app](https://github.com/aastik0303/fruit_fly_autodrive/blob/main/backend/api/main.py): `backend/api/main.py`
- [Neuron API](https://github.com/aastik0303/fruit_fly_autodrive/blob/main/backend/api/store.py): `backend/api/store.py`
- [Game WebSocket](https://github.com/aastik0303/fruit_fly_autodrive/blob/main/backend/api/game.py): `backend/api/game.py`
- [Eye encoding](https://github.com/aastik0303/fruit_fly_autodrive/blob/main/backend/embodied/eye.py): `backend/embodied/eye.py`
- [Connectome response](https://github.com/aastik0303/fruit_fly_autodrive/blob/main/backend/embodied/brain.py): `backend/embodied/brain.py`
- [Dodge environment](https://github.com/aastik0303/fruit_fly_autodrive/blob/main/backend/embodied/dodge_env.py): `backend/embodied/dodge_env.py`
- [Q-learning agent](https://github.com/aastik0303/fruit_fly_autodrive/blob/main/backend/embodied/agent.py): `backend/embodied/agent.py`
- [Agent training](https://github.com/aastik0303/fruit_fly_autodrive/blob/main/backend/embodied/train.py): `backend/embodied/train.py`

### Connectome explorer

- [Frontend app](https://github.com/aastik0303/fruit_fly_autodrive/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Neuron explorer](https://github.com/aastik0303/fruit_fly_autodrive/blob/main/frontend/src/pages/ExplorerPage.jsx): `frontend/src/pages/ExplorerPage.jsx`
- [REST client](https://github.com/aastik0303/fruit_fly_autodrive/blob/main/frontend/src/services/api.js): `frontend/src/services/api.js`
- [Connectome scene](https://github.com/aastik0303/fruit_fly_autodrive/blob/main/frontend/src/three/BrainScene.jsx): `frontend/src/three/BrainScene.jsx`

### Embodied game

- [Game interface](https://github.com/aastik0303/fruit_fly_autodrive/blob/main/frontend/src/pages/FlyGamePage.jsx): `frontend/src/pages/FlyGamePage.jsx`
- [Game socket client](https://github.com/aastik0303/fruit_fly_autodrive/blob/main/frontend/src/services/gameSocket.js): `frontend/src/services/gameSocket.js`
- [Game arena](https://github.com/aastik0303/fruit_fly_autodrive/blob/main/frontend/src/three/GameArena.jsx): `frontend/src/three/GameArena.jsx`
- [Brain activity view](https://github.com/aastik0303/fruit_fly_autodrive/blob/main/frontend/src/three/BrainActivity.jsx): `frontend/src/three/BrainActivity.jsx`

### Other components

- **Researcher**

## Connections

- Researcher → Frontend app: opens (evidence: `frontend/src/App.jsx`)
- Frontend app → Neuron explorer: renders (evidence: `frontend/src/App.jsx`)
- Frontend app → Game interface: renders (evidence: `frontend/src/App.jsx`)
- Data ingestion → Processed tables: writes (evidence: `backend/preprocessing/ingest.py`)
- Table loaders → Processed tables: reads (evidence: `backend/preprocessing/loaders.py`)
- API app → Neuron API: registers (evidence: `backend/api/main.py`)
- API app → Game WebSocket: registers (evidence: `backend/api/main.py`)
- Neuron API → Table loaders: loads (evidence: `backend/api/store.py`)
- Neuron explorer → REST client: requests data (evidence: `frontend/src/pages/ExplorerPage.jsx`)
- REST client → Neuron API: requests neuron data (evidence: `README.md`)
- Neuron explorer → Connectome scene: renders (evidence: `frontend/src/pages/ExplorerPage.jsx`)
- Game interface → Game socket client: connects (evidence: `frontend/src/pages/FlyGamePage.jsx`)
- Game socket client → Game WebSocket: exchanges commands (evidence: `backend/api/game.py`)
- Game interface → REST client: requests point cloud (evidence: `frontend/src/pages/FlyGamePage.jsx`)
- REST client → Neuron API: requests visualization (evidence: `README.md`)
- Game interface → Game arena: renders (evidence: `frontend/src/pages/FlyGamePage.jsx`)
- Game interface → Brain activity view: renders (evidence: `frontend/src/pages/FlyGamePage.jsx`)
- Game WebSocket → Dodge environment: advances game (evidence: `backend/api/game.py`)
- Game WebSocket → Eye encoding: encodes view (evidence: `backend/api/game.py`)
- Game WebSocket → Connectome response: computes activity (evidence: `backend/api/game.py`)
- Game WebSocket → Q-learning agent: selects action (evidence: `backend/api/game.py`)
- Connectome response → Eye encoding: uses input matrix (evidence: `backend/embodied/brain.py`)
- Connectome response → Table loaders: loads connectome (evidence: `backend/embodied/brain.py`)
- Eye encoding → Dodge environment: uses game geometry (evidence: `backend/embodied/eye.py`)
- Agent training → Connectome response: trains against (evidence: `backend/embodied/train.py`)
- Agent training → Q-learning agent: trains (evidence: `backend/embodied/train.py`)
- Agent training → Dodge environment: simulates episodes (evidence: `backend/embodied/train.py`)
- Agent training → Eye encoding: featurizes views (evidence: `backend/embodied/train.py`)
- Game arena → Brain activity view: displays alongside
