# tsutokiteo/tsukibrain architecture

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

- Interactive diagram: https://gitdiagram.com/tsutokiteo/tsukibrain
- Repository: https://github.com/tsutokiteo/tsukibrain

## Overview

TsukiBrain combines a feed-control GUI, a connectome-based neural simulation, and Blender avatar reactions. The GUI writes feed events; the simulator reads them and emits neural-state JSON, while Blender independently polls the feed file and applies timed mouth and ear reactions. The README describes a broader topology-to-avatar motion workflow, but the sampled listener does not read the simulator output, so that integration is not shown as a runtime connection. The external fly-brain clone supplies connectome data; its internals were not sampled.

Main entry points: [`bridge/flybrain_topology.py`](https://github.com/tsutokiteo/tsukibrain/blob/master/bridge/flybrain_topology.py) (Topology Simulation), [`bridge/feed_listener.py`](https://github.com/tsutokiteo/tsukibrain/blob/master/bridge/feed_listener.py) (Blender Listener), [`output/feed_signal.json`](https://github.com/tsutokiteo/tsukibrain/blob/master/output/feed_signal.json) (Feed Signal), [`bridge/feed_gui.py`](https://github.com/tsutokiteo/tsukibrain/blob/master/bridge/feed_gui.py) (Feed GUI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_feed["Feed Control"]
  node_feed_gui["Feed GUI<br/>[feed_gui.py]"]
end

subgraph group_neural["Neural Simulation"]
  node_topology["Topology Simulation"]
end

subgraph group_avatar["Avatar Response"]
  node_blender_listener["Blender Listener<br/>[feed_listener.py]"]
  node_ear_tail["Ear and Tail Motion<br/>[feed_listener.py]"]
  node_mouth_shapes["Mouth Shape Keys<br/>[feed_listener.py]"]
  node_avatar["3D Avatar"]
end

subgraph group_data["Data Artifacts"]
  node_feed_signal["Feed Signal<br/>[feed_signal.json]"]
  node_connectome[("Fly-Brain Data")]
  node_neural_output["Neural State"]
end

node_user(("User"))

node_user -->|"sets feed"| node_feed_gui
node_feed_gui -->|"writes event"| node_feed_signal
node_topology -->|"loads connectivity"| node_connectome
node_topology -->|"reads event"| node_feed_signal
node_topology -->|"writes state"| node_neural_output
node_blender_listener -->|"polls event"| node_feed_signal
node_blender_listener -->|"moves bones"| node_ear_tail
node_blender_listener -->|"sets shapes"| node_mouth_shapes
node_ear_tail -->|"animates"| node_avatar
node_mouth_shapes -->|"animates"| node_avatar

click node_feed_gui "https://github.com/tsutokiteo/tsukibrain/blob/master/bridge/feed_gui.py"
click node_feed_signal "https://github.com/tsutokiteo/tsukibrain/blob/master/output/feed_signal.json"
click node_topology "https://github.com/tsutokiteo/tsukibrain/blob/master/bridge/flybrain_topology.py"
click node_connectome "https://github.com/tsutokiteo/tsukibrain/tree/master/repos/fly-brain"
click node_neural_output "https://github.com/tsutokiteo/tsukibrain/blob/master/output/flybrain_output.json"
click node_blender_listener "https://github.com/tsutokiteo/tsukibrain/blob/master/bridge/feed_listener.py"
click node_ear_tail "https://github.com/tsutokiteo/tsukibrain/blob/master/bridge/feed_listener.py"
click node_mouth_shapes "https://github.com/tsutokiteo/tsukibrain/blob/master/bridge/feed_listener.py"

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_feed_gui,node_user toneBlue
class node_topology toneAmber
class node_blender_listener,node_ear_tail,node_mouth_shapes,node_avatar toneMint
class node_feed_signal,node_connectome,node_neural_output toneRose
```

## Components

### Feed Control

- [Feed GUI](https://github.com/tsutokiteo/tsukibrain/blob/master/bridge/feed_gui.py): `bridge/feed_gui.py`

### Neural Simulation

- [Topology Simulation](https://github.com/tsutokiteo/tsukibrain/blob/master/bridge/flybrain_topology.py): `bridge/flybrain_topology.py`

### Avatar Response

- [Blender Listener](https://github.com/tsutokiteo/tsukibrain/blob/master/bridge/feed_listener.py): `bridge/feed_listener.py`
- [Ear and Tail Motion](https://github.com/tsutokiteo/tsukibrain/blob/master/bridge/feed_listener.py): `bridge/feed_listener.py`
- [Mouth Shape Keys](https://github.com/tsutokiteo/tsukibrain/blob/master/bridge/feed_listener.py): `bridge/feed_listener.py`
- **3D Avatar**

### Data Artifacts

- [Feed Signal](https://github.com/tsutokiteo/tsukibrain/blob/master/output/feed_signal.json): `output/feed_signal.json`
- [Fly-Brain Data](https://github.com/tsutokiteo/tsukibrain/tree/master/repos/fly-brain): `repos/fly-brain`
- [Neural State](https://github.com/tsutokiteo/tsukibrain/blob/master/output/flybrain_output.json): `output/flybrain_output.json`

### Other components

- **User**

## Connections

- User → Feed GUI: sets feed (evidence: `bridge/feed_gui.py`)
- Feed GUI → Feed Signal: writes event (evidence: `bridge/feed_gui.py`)
- Topology Simulation → Fly-Brain Data: loads connectivity (evidence: `bridge/flybrain_topology.py`)
- Topology Simulation → Feed Signal: reads event (evidence: `bridge/flybrain_topology.py`)
- Topology Simulation → Neural State: writes state (evidence: `bridge/flybrain_topology.py`)
- Blender Listener → Feed Signal: polls event (evidence: `bridge/feed_listener.py`)
- Blender Listener → Ear and Tail Motion: moves bones (evidence: `bridge/feed_listener.py`)
- Blender Listener → Mouth Shape Keys: sets shapes (evidence: `bridge/feed_listener.py`)
- Ear and Tail Motion → 3D Avatar: animates (evidence: `bridge/feed_listener.py`)
- Mouth Shape Keys → 3D Avatar: animates (evidence: `bridge/feed_listener.py`)
