# ns2250225/fly-flappy architecture

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

## Overview

This browser-based experiment runs Flappy Bird under control of a frozen fruit-fly connectome, with PURE BRAIN, ONLINE TRAIN, and FAST MODEL modes. The main workflow is: the player starts a flight; the app advances the game and sends captured state to the brain worker; the worker encodes sensory input, simulates neural activity, decodes a flap decision, and returns activity and training results; the app applies the decision and renders the game and neural map. Training/model management and experiment history are additional branches. Worker internals and several UI handlers are only partly sampled, so uncertain links are omitted.

Main entry points: [`src/App.ts`](https://github.com/ns2250225/fly-flappy/blob/main/src/App.ts) (App coordinator), [`src/brain/flyBrain.worker.ts`](https://github.com/ns2250225/fly-flappy/blob/main/src/brain/flyBrain.worker.ts) (Brain worker), [`src/game/FlappyGame.ts`](https://github.com/ns2250225/fly-flappy/blob/main/src/game/FlappyGame.ts) (Flappy game), [`src/brain/FlyBrain.ts`](https://github.com/ns2250225/fly-flappy/blob/main/src/brain/FlyBrain.ts) (Brain client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Application UI"]
  node_app["App coordinator<br/>[App.ts]"]
  node_gameview["Game renderer<br/>[GameRenderer.ts]"]
  node_brainview["Brain renderer<br/>[BrainRenderer.ts]"]
end

subgraph group_game["Flight simulation"]
  node_game["Flappy game<br/>[FlappyGame.ts]"]
  node_bird["Bird physics<br/>[Bird.ts]"]
  node_pipes["Pipe obstacles<br/>[Pipe.ts]"]
  node_collision["Collision checks<br/>[Collision.ts]"]
end

subgraph group_brain["Connectome runtime"]
  node_brainclient["Brain client<br/>[FlyBrain.ts]"]
  node_worker["Brain worker<br/>[flyBrain.worker.ts]"]
  node_encoder["Sensory encoder<br/>[FlyEncoder.ts]"]
  node_decoder["Action decoder<br/>[FlyDecoder.ts]"]
  node_readout["Learned readout<br/>[Readout.ts]"]
  node_policy["Flight safety policy"]
  node_loader["Connectome loader<br/>[BrainLoader.ts]"]
  node_braindata["Connectome assets"]
end

subgraph group_records["Training and records"]
  node_history["Experiment history"]
  node_random["Seeded randomness<br/>[SeededRandom.ts]"]
end

node_player(("Player"))
node_storage[("Browser local storage")]
node_browser["Browser"]

node_player -->|"starts and controls"| node_app
node_browser -->|"runs"| node_app
node_app -->|"loads manifest"| node_loader
node_loader -->|"fetches manifest"| node_braindata
node_app -->|"initializes and steps"| node_brainclient
node_brainclient -->|"dispatches requests"| node_worker
node_worker -->|"fetches connectome and model"| node_braindata
node_worker -->|"encodes game state"| node_encoder
node_worker -->|"infers and trains"| node_readout
node_worker -->|"applies training policy"| node_policy
node_worker -->|"decodes action"| node_decoder
node_worker -->|"returns results"| node_brainclient
node_app -->|"updates and captures state"| node_game
node_game -->|"updates"| node_bird
node_game -->|"spawns and updates"| node_pipes
node_game -->|"checks collisions"| node_collision
node_app -->|"applies flap decision"| node_game
node_app -->|"renders flight"| node_gameview
node_app -->|"renders activity"| node_brainview
node_app -->|"records flight results"| node_history
node_history -->|"reads and writes records"| node_storage
node_app -->|"loads and saves online model"| node_storage
node_game -->|"seeds pipe placement"| node_random

click node_app "https://github.com/ns2250225/fly-flappy/blob/main/src/App.ts"
click node_game "https://github.com/ns2250225/fly-flappy/blob/main/src/game/FlappyGame.ts"
click node_bird "https://github.com/ns2250225/fly-flappy/blob/main/src/game/Bird.ts"
click node_pipes "https://github.com/ns2250225/fly-flappy/blob/main/src/game/Pipe.ts"
click node_collision "https://github.com/ns2250225/fly-flappy/blob/main/src/game/Collision.ts"
click node_gameview "https://github.com/ns2250225/fly-flappy/blob/main/src/renderer/GameRenderer.ts"
click node_brainview "https://github.com/ns2250225/fly-flappy/blob/main/src/renderer/BrainRenderer.ts"
click node_brainclient "https://github.com/ns2250225/fly-flappy/blob/main/src/brain/FlyBrain.ts"
click node_worker "https://github.com/ns2250225/fly-flappy/blob/main/src/brain/flyBrain.worker.ts"
click node_encoder "https://github.com/ns2250225/fly-flappy/blob/main/src/brain/FlyEncoder.ts"
click node_decoder "https://github.com/ns2250225/fly-flappy/blob/main/src/brain/FlyDecoder.ts"
click node_readout "https://github.com/ns2250225/fly-flappy/blob/main/src/brain/Readout.ts"
click node_policy "https://github.com/ns2250225/fly-flappy/blob/main/src/brain/TrainedFlightPolicy.ts"
click node_loader "https://github.com/ns2250225/fly-flappy/blob/main/src/brain/BrainLoader.ts"
click node_braindata "https://github.com/ns2250225/fly-flappy/tree/main/public/brain"
click node_history "https://github.com/ns2250225/fly-flappy/blob/main/src/experiment/ExperimentHistory.ts"
click node_random "https://github.com/ns2250225/fly-flappy/blob/main/src/experiment/SeededRandom.ts"

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_app,node_gameview,node_brainview,node_browser toneBlue
class node_game,node_bird,node_pipes,node_collision,node_storage toneAmber
class node_brainclient,node_worker,node_encoder,node_decoder,node_readout,node_policy,node_loader,node_braindata toneMint
class node_history,node_random toneRose
class node_player toneIndigo
```

## Components

### Application UI

- [App coordinator](https://github.com/ns2250225/fly-flappy/blob/main/src/App.ts): `src/App.ts`
- [Game renderer](https://github.com/ns2250225/fly-flappy/blob/main/src/renderer/GameRenderer.ts): `src/renderer/GameRenderer.ts`
- [Brain renderer](https://github.com/ns2250225/fly-flappy/blob/main/src/renderer/BrainRenderer.ts): `src/renderer/BrainRenderer.ts`

### Flight simulation

- [Flappy game](https://github.com/ns2250225/fly-flappy/blob/main/src/game/FlappyGame.ts): `src/game/FlappyGame.ts`
- [Bird physics](https://github.com/ns2250225/fly-flappy/blob/main/src/game/Bird.ts): `src/game/Bird.ts`
- [Pipe obstacles](https://github.com/ns2250225/fly-flappy/blob/main/src/game/Pipe.ts): `src/game/Pipe.ts`
- [Collision checks](https://github.com/ns2250225/fly-flappy/blob/main/src/game/Collision.ts): `src/game/Collision.ts`

### Connectome runtime

- [Brain client](https://github.com/ns2250225/fly-flappy/blob/main/src/brain/FlyBrain.ts): `src/brain/FlyBrain.ts`
- [Brain worker](https://github.com/ns2250225/fly-flappy/blob/main/src/brain/flyBrain.worker.ts): `src/brain/flyBrain.worker.ts`
- [Sensory encoder](https://github.com/ns2250225/fly-flappy/blob/main/src/brain/FlyEncoder.ts): `src/brain/FlyEncoder.ts`
- [Action decoder](https://github.com/ns2250225/fly-flappy/blob/main/src/brain/FlyDecoder.ts): `src/brain/FlyDecoder.ts`
- [Learned readout](https://github.com/ns2250225/fly-flappy/blob/main/src/brain/Readout.ts): `src/brain/Readout.ts`
- [Flight safety policy](https://github.com/ns2250225/fly-flappy/blob/main/src/brain/TrainedFlightPolicy.ts): `src/brain/TrainedFlightPolicy.ts`
- [Connectome loader](https://github.com/ns2250225/fly-flappy/blob/main/src/brain/BrainLoader.ts): `src/brain/BrainLoader.ts`
- [Connectome assets](https://github.com/ns2250225/fly-flappy/tree/main/public/brain): `public/brain`

### Training and records

- [Experiment history](https://github.com/ns2250225/fly-flappy/blob/main/src/experiment/ExperimentHistory.ts): `src/experiment/ExperimentHistory.ts`
- [Seeded randomness](https://github.com/ns2250225/fly-flappy/blob/main/src/experiment/SeededRandom.ts): `src/experiment/SeededRandom.ts`

### Other components

- **Player**
- **Browser local storage**
- **Browser**

## Connections

- Player → App coordinator: starts and controls
- Browser → App coordinator: runs
- App coordinator → Connectome loader: loads manifest
- Connectome loader → Connectome assets: fetches manifest
- App coordinator → Brain client: initializes and steps
- Brain client → Brain worker: dispatches requests
- Brain worker → Connectome assets: fetches connectome and model
- Brain worker → Sensory encoder: encodes game state
- Brain worker → Learned readout: infers and trains
- Brain worker → Flight safety policy: applies training policy
- Brain worker → Action decoder: decodes action
- Brain worker → Brain client: returns results
- App coordinator → Flappy game: updates and captures state
- Flappy game → Bird physics: updates
- Flappy game → Pipe obstacles: spawns and updates
- Flappy game → Collision checks: checks collisions
- App coordinator → Flappy game: applies flap decision
- App coordinator → Game renderer: renders flight
- App coordinator → Brain renderer: renders activity
- App coordinator → Experiment history: records flight results
- Experiment history → Browser local storage: reads and writes records
- App coordinator → Browser local storage: loads and saves online model
- Flappy game → Seeded randomness: seeds pipe placement