# jxsh341/project-icarus architecture

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

- Interactive diagram: https://gitdiagram.com/jxsh341/project-icarus
- Repository: https://github.com/jxsh341/project-icarus

## Overview

fly-cognition is a connectome-derived neural research model for studying innate behavior, associative learning, retention, and forgetting. Its principal workflow is to obtain and transform connectome records, construct signed connectivity, simulate neural activity, and train or modify synaptic weights; experiments then evaluate behavioral and substrate-level outcomes. The repository also documents a closed-loop embodiment scaffold and distinct forgetting-certification and synaptic-erasure studies. Some experimental subsystems are represented by their exact scripts or directories because their implementations were not sampled; links without direct evidence are omitted.

Main entry points: [`fly/training.py`](https://github.com/jxsh341/project-icarus/blob/main/fly/training.py) (Training driver), [`fly/embodiment/sensorimotor_loop.py`](https://github.com/jxsh341/project-icarus/blob/main/fly/embodiment/sensorimotor_loop.py) (Sensorimotor loop), [`fly/data/loader.py`](https://github.com/jxsh341/project-icarus/blob/main/fly/data/loader.py) (Snapshot loader), [`fly/dynamics/lif.py`](https://github.com/jxsh341/project-icarus/blob/main/fly/dynamics/lif.py) (LIF simulation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_connectome["Connectome data"]
  node_loader["Snapshot loader<br/>[loader.py]"]
  node_schemas["Data schemas<br/>[schemas.py]"]
  node_provenance["Provenance<br/>[provenance.py]"]
  node_transform["Record transform<br/>[transform.py]"]
  node_neuron_records["Neuron records<br/>[models.py]"]
  node_synapse_records["Synapse records<br/>[models.py]"]
end

subgraph group_substrate["Neural substrate"]
  node_connectivity["Signed connectivity<br/>[graph.py]"]
  node_lif["LIF simulation<br/>[lif.py]"]
  node_api["Substrate API<br/>[api.py]"]
end

subgraph group_learning["Learning and embodiment"]
  node_plasticity["Plasticity rules<br/>[plasticity.py]"]
  node_training["Training driver<br/>[training.py]"]
  node_body_graph["Body and sensors<br/>[body_graph.py]"]
  node_sensorimotor["Sensorimotor loop"]
end

subgraph group_experiments["Research experiments"]
  node_acquisition["Acquisition studies"]
  node_eligibility_sign["Eligibility and sign"]
  node_confirmatory["Extinction analysis"]
  node_forgetting["Forgetting oracle"]
  node_rank_decay["Targeted erasure"]
  node_embodiment_study["Closed-loop study"]
end

node_neuprint(("neuPrint"))

node_neuprint -->|"supplies snapshots"| node_loader
node_loader -->|"loads records"| node_neuron_records
node_loader -->|"loads records"| node_synapse_records
node_neuron_records -->|"provides neurons"| node_connectivity
node_synapse_records -->|"provides synapses"| node_connectivity
node_api -->|"simulates trials"| node_lif
node_training -->|"runs trials"| node_lif
node_training -->|"applies updates"| node_plasticity
node_sensorimotor -->|"reads sensors"| node_body_graph
node_sensorimotor -->|"simulates step"| node_lif
node_acquisition -->|"runs learning"| node_training
node_eligibility_sign -->|"configures unlearning"| node_training
node_confirmatory -.->|"feeds evaluation"| node_forgetting
node_forgetting -.->|"compares erasure"| node_rank_decay
node_sensorimotor -.->|"supports closed-loop study"| node_embodiment_study

click node_loader "https://github.com/jxsh341/project-icarus/blob/main/fly/data/loader.py"
click node_schemas "https://github.com/jxsh341/project-icarus/blob/main/fly/data/schemas.py"
click node_provenance "https://github.com/jxsh341/project-icarus/blob/main/fly/data/provenance.py"
click node_transform "https://github.com/jxsh341/project-icarus/blob/main/fly/data/transform.py"
click node_neuron_records "https://github.com/jxsh341/project-icarus/blob/main/fly/neurons/models.py"
click node_synapse_records "https://github.com/jxsh341/project-icarus/blob/main/fly/synapses/models.py"
click node_connectivity "https://github.com/jxsh341/project-icarus/blob/main/fly/network/graph.py"
click node_lif "https://github.com/jxsh341/project-icarus/blob/main/fly/dynamics/lif.py"
click node_api "https://github.com/jxsh341/project-icarus/blob/main/fly/api.py"
click node_plasticity "https://github.com/jxsh341/project-icarus/blob/main/fly/plasticity.py"
click node_training "https://github.com/jxsh341/project-icarus/blob/main/fly/training.py"
click node_body_graph "https://github.com/jxsh341/project-icarus/blob/main/fly/embodiment/body_graph.py"
click node_sensorimotor "https://github.com/jxsh341/project-icarus/blob/main/fly/embodiment/sensorimotor_loop.py"
click node_acquisition "https://github.com/jxsh341/project-icarus/blob/main/scripts/phase2_wp3_pilot.py"
click node_eligibility_sign "https://github.com/jxsh341/project-icarus/blob/main/scripts/phase4_eligibility_sign_rule.py"
click node_confirmatory "https://github.com/jxsh341/project-icarus/blob/main/scripts/phase5_expA_analysis.py"
click node_forgetting "https://github.com/jxsh341/project-icarus/blob/main/scripts/phase6_l6a_oracle.py"
click node_rank_decay "https://github.com/jxsh341/project-icarus/blob/main/scripts/phase6_wp_l6b_rankforget.py"
click node_embodiment_study "https://github.com/jxsh341/project-icarus/blob/main/scripts/phase7e1_harness.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_loader,node_schemas,node_provenance,node_transform,node_neuron_records,node_synapse_records toneBlue
class node_connectivity,node_lif,node_api toneAmber
class node_plasticity,node_training,node_body_graph,node_sensorimotor toneMint
class node_acquisition,node_eligibility_sign,node_confirmatory,node_forgetting,node_rank_decay,node_embodiment_study toneRose
class node_neuprint toneIndigo
```

## Components

### Connectome data

- [Snapshot loader](https://github.com/jxsh341/project-icarus/blob/main/fly/data/loader.py): `fly/data/loader.py`
- [Data schemas](https://github.com/jxsh341/project-icarus/blob/main/fly/data/schemas.py): `fly/data/schemas.py`
- [Provenance](https://github.com/jxsh341/project-icarus/blob/main/fly/data/provenance.py): `fly/data/provenance.py`
- [Record transform](https://github.com/jxsh341/project-icarus/blob/main/fly/data/transform.py): `fly/data/transform.py`
- [Neuron records](https://github.com/jxsh341/project-icarus/blob/main/fly/neurons/models.py): `fly/neurons/models.py`
- [Synapse records](https://github.com/jxsh341/project-icarus/blob/main/fly/synapses/models.py): `fly/synapses/models.py`

### Neural substrate

- [Signed connectivity](https://github.com/jxsh341/project-icarus/blob/main/fly/network/graph.py): `fly/network/graph.py`
- [LIF simulation](https://github.com/jxsh341/project-icarus/blob/main/fly/dynamics/lif.py): `fly/dynamics/lif.py`
- [Substrate API](https://github.com/jxsh341/project-icarus/blob/main/fly/api.py): `fly/api.py`

### Learning and embodiment

- [Plasticity rules](https://github.com/jxsh341/project-icarus/blob/main/fly/plasticity.py): `fly/plasticity.py`
- [Training driver](https://github.com/jxsh341/project-icarus/blob/main/fly/training.py): `fly/training.py`
- [Body and sensors](https://github.com/jxsh341/project-icarus/blob/main/fly/embodiment/body_graph.py): `fly/embodiment/body_graph.py`
- [Sensorimotor loop](https://github.com/jxsh341/project-icarus/blob/main/fly/embodiment/sensorimotor_loop.py): `fly/embodiment/sensorimotor_loop.py`

### Research experiments

- [Acquisition studies](https://github.com/jxsh341/project-icarus/blob/main/scripts/phase2_wp3_pilot.py): `scripts/phase2_wp3_pilot.py`
- [Eligibility and sign](https://github.com/jxsh341/project-icarus/blob/main/scripts/phase4_eligibility_sign_rule.py): `scripts/phase4_eligibility_sign_rule.py`
- [Extinction analysis](https://github.com/jxsh341/project-icarus/blob/main/scripts/phase5_expA_analysis.py): `scripts/phase5_expA_analysis.py`
- [Forgetting oracle](https://github.com/jxsh341/project-icarus/blob/main/scripts/phase6_l6a_oracle.py): `scripts/phase6_l6a_oracle.py`
- [Targeted erasure](https://github.com/jxsh341/project-icarus/blob/main/scripts/phase6_wp_l6b_rankforget.py): `scripts/phase6_wp_l6b_rankforget.py`
- [Closed-loop study](https://github.com/jxsh341/project-icarus/blob/main/scripts/phase7e1_harness.py): `scripts/phase7e1_harness.py`

### Other components

- **neuPrint**

## Connections

- neuPrint → Snapshot loader: supplies snapshots (evidence: `README.md`)
- Snapshot loader → Neuron records: loads records (evidence: `fly/data/loader.py`)
- Snapshot loader → Synapse records: loads records (evidence: `fly/data/loader.py`)
- Neuron records → Signed connectivity: provides neurons (evidence: `fly/network/graph.py`)
- Synapse records → Signed connectivity: provides synapses (evidence: `fly/network/graph.py`)
- Substrate API → LIF simulation: simulates trials (evidence: `fly/api.py`)
- Training driver → LIF simulation: runs trials (evidence: `fly/training.py`)
- Training driver → Plasticity rules: applies updates (evidence: `fly/training.py`)
- Sensorimotor loop → Body and sensors: reads sensors (evidence: `fly/embodiment/sensorimotor_loop.py`)
- Sensorimotor loop → LIF simulation: simulates step (evidence: `fly/embodiment/sensorimotor_loop.py`)
- Acquisition studies → Training driver: runs learning (evidence: `scripts/phase2_wp3_pilot.py`)
- Eligibility and sign → Training driver: configures unlearning
- Extinction analysis → Forgetting oracle: feeds evaluation (evidence: `scripts/phase6_l6a_oracle.py`)
- Forgetting oracle → Targeted erasure: compares erasure
- Sensorimotor loop → Closed-loop study: supports closed-loop study
