# andreaj42/cortexforge architecture

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

## Overview

CorteXforge plans radio experiments, executes them on CorteXlab transmitter, receiver, and synchronization nodes, and provides a separate API/CLI for downloading pre-generated datasets. The main workflow is planner configuration → scenario and timeline generation → role-based Forge execution → labeled SigMF recordings. The graph also preserves the dataset-access and waveform-generation capabilities. Some subsystem relationships are documented in the README or SOURCE INDEX; unsampled internals are not assumed to call one another.

Main entry points: [`src/cortexforge/forge/radio/rx.py`](https://github.com/andreaj42/cortexforge/blob/main/src/cortexforge/forge/radio/rx.py) (Receiver capture), [`src/cortexforge/planner/main.py`](https://github.com/andreaj42/cortexforge/blob/main/src/cortexforge/planner/main.py) (Scenario orchestration), [`src/cortexforge/forge/main.py`](https://github.com/andreaj42/cortexforge/blob/main/src/cortexforge/forge/main.py) (Role dispatcher), [`src/cortexforge/forge/radio/tx.py`](https://github.com/andreaj42/cortexforge/blob/main/src/cortexforge/forge/radio/tx.py) (Transmitter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_planning["Experiment planning"]
  node_planner_cli["Planner CLI<br/>[planner.py]"]
  node_planner_main["Scenario orchestration<br/>[main.py]"]
  node_experiment_scenario["Timeline generator"]
  node_cortexlab_scenario["Deployment scenario"]
  node_modulations["Modulation definitions<br/>[modulations.py]"]
end

subgraph group_execution["Forge execution"]
  node_forge_cli["Forge CLI<br/>[forge.py]"]
  node_forge_main["Role dispatcher<br/>[main.py]"]
  node_sync["Sync coordinator<br/>[sync.py]"]
  node_sync_client["Sync barrier client"]
  node_sync_server["Sync barrier server"]
end

subgraph group_radio["Radio and metadata"]
  node_tx["Transmitter<br/>[tx.py]"]
  node_waveforms["Waveform generation"]
  node_pulse_shaping["Pulse shaping<br/>[pulse_shaping.py]"]
  node_rx["Receiver capture<br/>[rx.py]"]
  node_rx_recorder["GNU Radio recorder<br/>[rx_recorder.py]"]
  node_baseline["Power analysis"]
  node_annotations["SigMF annotations"]
  node_sigmf_writer["SigMF writer<br/>[sigmf_writer.py]"]
  node_recordings["SigMF recordings"]
end

subgraph group_datasets["Dataset access"]
  node_datasets_cli["Datasets CLI<br/>[main.py]"]
  node_dataset_api["Dataset API<br/>[api.py]"]
  node_dataset_local["Local dataset access<br/>[local.py]"]
  node_dataset_manifest["Dataset manifest<br/>[manifest.py]"]
  node_dataset_store[("Dataset files")]
end

node_user(("Experiment user"))
node_cortexlab["CorteXlab testbed"]
node_dataset_user(("Dataset user"))

node_user -->|"configures"| node_planner_cli
node_planner_cli -->|"parses arguments"| node_planner_main
node_planner_main -->|"generates timeline"| node_experiment_scenario
node_planner_main -->|"generates deployment"| node_cortexlab_scenario
node_experiment_scenario -->|"uses definitions"| node_modulations
node_planner_main -->|"targets deployment"| node_cortexlab
node_cortexlab -->|"runs node roles"| node_forge_cli
node_forge_cli -->|"parses arguments"| node_forge_main
node_forge_main -->|"dispatches TX"| node_tx
node_forge_main -->|"dispatches RX"| node_rx
node_forge_main -->|"dispatches sync"| node_sync
node_tx -->|"uses waveforms"| node_waveforms
node_waveforms -->|"uses shaping"| node_pulse_shaping
node_waveforms -->|"uses definitions"| node_modulations
node_rx -->|"records samples"| node_rx_recorder
node_rx -->|"registers and waits"| node_sync_client
node_tx -->|"registers and waits"| node_sync_client
node_sync -->|"runs barrier server"| node_sync_server
node_sync_client -.->|"exchanges readiness"| node_sync_server
node_rx -->|"computes baseline"| node_baseline
node_rx -->|"creates labels"| node_annotations
node_annotations -->|"measures band power"| node_baseline
node_rx -->|"writes metadata"| node_sigmf_writer
node_sigmf_writer -->|"writes recording files"| node_recordings
node_recordings -->|"copies to shared storage"| node_cortexlab
node_dataset_user -->|"lists or downloads"| node_datasets_cli
node_datasets_cli -->|"requests datasets"| node_dataset_api
node_dataset_api -->|"uses local access"| node_dataset_local
node_dataset_api -->|"reads manifest"| node_dataset_manifest
node_dataset_local -->|"uses manifest data"| node_dataset_manifest
node_dataset_local -.->|"installs datasets"| node_dataset_store

click node_planner_cli "https://github.com/andreaj42/cortexforge/blob/main/src/cortexforge/cli/planner.py"
click node_planner_main "https://github.com/andreaj42/cortexforge/blob/main/src/cortexforge/planner/main.py"
click node_experiment_scenario "https://github.com/andreaj42/cortexforge/blob/main/src/cortexforge/planner/generators/experiment_scenario.py"
click node_cortexlab_scenario "https://github.com/andreaj42/cortexforge/blob/main/src/cortexforge/planner/generators/cortexlab_scenario.py"
click node_modulations "https://github.com/andreaj42/cortexforge/blob/main/src/cortexforge/modulations.py"
click node_forge_cli "https://github.com/andreaj42/cortexforge/blob/main/src/cortexforge/cli/forge.py"
click node_forge_main "https://github.com/andreaj42/cortexforge/blob/main/src/cortexforge/forge/main.py"
click node_tx "https://github.com/andreaj42/cortexforge/blob/main/src/cortexforge/forge/radio/tx.py"
click node_waveforms "https://github.com/andreaj42/cortexforge/blob/main/src/cortexforge/forge/radio/waveforms_digital.py"
click node_pulse_shaping "https://github.com/andreaj42/cortexforge/blob/main/src/cortexforge/forge/radio/pulse_shaping.py"
click node_rx "https://github.com/andreaj42/cortexforge/blob/main/src/cortexforge/forge/radio/rx.py"
click node_rx_recorder "https://github.com/andreaj42/cortexforge/blob/main/src/cortexforge/forge/radio/rx_recorder.py"
click node_sync "https://github.com/andreaj42/cortexforge/blob/main/src/cortexforge/forge/sync.py"
click node_sync_client "https://github.com/andreaj42/cortexforge/blob/main/src/cortexforge/forge/utils/sync_barrier/sync_barrier_client.py"
click node_sync_server "https://github.com/andreaj42/cortexforge/blob/main/src/cortexforge/forge/utils/sync_barrier/sync_barrier_server.py"
click node_baseline "https://github.com/andreaj42/cortexforge/blob/main/src/cortexforge/forge/utils/compute_baseline.py"
click node_annotations "https://github.com/andreaj42/cortexforge/blob/main/src/cortexforge/forge/utils/sigmf/sigmf_annotations.py"
click node_sigmf_writer "https://github.com/andreaj42/cortexforge/blob/main/src/cortexforge/forge/utils/sigmf_writer.py"
click node_datasets_cli "https://github.com/andreaj42/cortexforge/blob/main/src/cortexforge/datasets/main.py"
click node_dataset_api "https://github.com/andreaj42/cortexforge/blob/main/src/cortexforge/datasets/api.py"
click node_dataset_local "https://github.com/andreaj42/cortexforge/blob/main/src/cortexforge/datasets/local.py"
click node_dataset_manifest "https://github.com/andreaj42/cortexforge/blob/main/src/cortexforge/datasets/manifest.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_planner_cli,node_planner_main,node_experiment_scenario,node_cortexlab_scenario,node_modulations,node_user,node_dataset_user toneBlue
class node_forge_cli,node_forge_main,node_sync,node_sync_client,node_sync_server toneAmber
class node_tx,node_waveforms,node_pulse_shaping,node_rx,node_rx_recorder,node_baseline,node_annotations,node_sigmf_writer,node_recordings toneMint
class node_datasets_cli,node_dataset_api,node_dataset_local,node_dataset_manifest,node_dataset_store toneRose
class node_cortexlab toneIndigo
```

## Components

### Experiment planning

- [Planner CLI](https://github.com/andreaj42/cortexforge/blob/main/src/cortexforge/cli/planner.py): `src/cortexforge/cli/planner.py`
- [Scenario orchestration](https://github.com/andreaj42/cortexforge/blob/main/src/cortexforge/planner/main.py): `src/cortexforge/planner/main.py`
- [Timeline generator](https://github.com/andreaj42/cortexforge/blob/main/src/cortexforge/planner/generators/experiment_scenario.py): `src/cortexforge/planner/generators/experiment_scenario.py`
- [Deployment scenario](https://github.com/andreaj42/cortexforge/blob/main/src/cortexforge/planner/generators/cortexlab_scenario.py): `src/cortexforge/planner/generators/cortexlab_scenario.py`
- [Modulation definitions](https://github.com/andreaj42/cortexforge/blob/main/src/cortexforge/modulations.py): `src/cortexforge/modulations.py`

### Forge execution

- [Forge CLI](https://github.com/andreaj42/cortexforge/blob/main/src/cortexforge/cli/forge.py): `src/cortexforge/cli/forge.py`
- [Role dispatcher](https://github.com/andreaj42/cortexforge/blob/main/src/cortexforge/forge/main.py): `src/cortexforge/forge/main.py`
- [Sync coordinator](https://github.com/andreaj42/cortexforge/blob/main/src/cortexforge/forge/sync.py): `src/cortexforge/forge/sync.py`
- [Sync barrier client](https://github.com/andreaj42/cortexforge/blob/main/src/cortexforge/forge/utils/sync_barrier/sync_barrier_client.py): `src/cortexforge/forge/utils/sync_barrier/sync_barrier_client.py`
- [Sync barrier server](https://github.com/andreaj42/cortexforge/blob/main/src/cortexforge/forge/utils/sync_barrier/sync_barrier_server.py): `src/cortexforge/forge/utils/sync_barrier/sync_barrier_server.py`

### Radio and metadata

- [Transmitter](https://github.com/andreaj42/cortexforge/blob/main/src/cortexforge/forge/radio/tx.py): `src/cortexforge/forge/radio/tx.py`
- [Waveform generation](https://github.com/andreaj42/cortexforge/blob/main/src/cortexforge/forge/radio/waveforms_digital.py): `src/cortexforge/forge/radio/waveforms_digital.py`
- [Pulse shaping](https://github.com/andreaj42/cortexforge/blob/main/src/cortexforge/forge/radio/pulse_shaping.py): `src/cortexforge/forge/radio/pulse_shaping.py`
- [Receiver capture](https://github.com/andreaj42/cortexforge/blob/main/src/cortexforge/forge/radio/rx.py): `src/cortexforge/forge/radio/rx.py`
- [GNU Radio recorder](https://github.com/andreaj42/cortexforge/blob/main/src/cortexforge/forge/radio/rx_recorder.py): `src/cortexforge/forge/radio/rx_recorder.py`
- [Power analysis](https://github.com/andreaj42/cortexforge/blob/main/src/cortexforge/forge/utils/compute_baseline.py): `src/cortexforge/forge/utils/compute_baseline.py`
- [SigMF annotations](https://github.com/andreaj42/cortexforge/blob/main/src/cortexforge/forge/utils/sigmf/sigmf_annotations.py): `src/cortexforge/forge/utils/sigmf/sigmf_annotations.py`
- [SigMF writer](https://github.com/andreaj42/cortexforge/blob/main/src/cortexforge/forge/utils/sigmf_writer.py): `src/cortexforge/forge/utils/sigmf_writer.py`
- **SigMF recordings**

### Dataset access

- [Datasets CLI](https://github.com/andreaj42/cortexforge/blob/main/src/cortexforge/datasets/main.py): `src/cortexforge/datasets/main.py`
- [Dataset API](https://github.com/andreaj42/cortexforge/blob/main/src/cortexforge/datasets/api.py): `src/cortexforge/datasets/api.py`
- [Local dataset access](https://github.com/andreaj42/cortexforge/blob/main/src/cortexforge/datasets/local.py): `src/cortexforge/datasets/local.py`
- [Dataset manifest](https://github.com/andreaj42/cortexforge/blob/main/src/cortexforge/datasets/manifest.py): `src/cortexforge/datasets/manifest.py`
- **Dataset files**

### Other components

- **Experiment user**
- **CorteXlab testbed**
- **Dataset user**

## Connections

- Experiment user → Planner CLI: configures
- Planner CLI → Scenario orchestration: parses arguments (evidence: `src/cortexforge/planner/main.py`)
- Scenario orchestration → Timeline generator: generates timeline (evidence: `src/cortexforge/planner/main.py`)
- Scenario orchestration → Deployment scenario: generates deployment (evidence: `src/cortexforge/planner/main.py`)
- Timeline generator → Modulation definitions: uses definitions (evidence: `src/cortexforge/planner/generators/experiment_scenario.py`)
- Scenario orchestration → CorteXlab testbed: targets deployment
- CorteXlab testbed → Forge CLI: runs node roles
- Forge CLI → Role dispatcher: parses arguments (evidence: `src/cortexforge/forge/main.py`)
- Role dispatcher → Transmitter: dispatches TX (evidence: `src/cortexforge/forge/main.py`)
- Role dispatcher → Receiver capture: dispatches RX (evidence: `src/cortexforge/forge/main.py`)
- Role dispatcher → Sync coordinator: dispatches sync (evidence: `src/cortexforge/forge/main.py`)
- Transmitter → Waveform generation: uses waveforms (evidence: `src/cortexforge/forge/radio/tx.py`)
- Waveform generation → Pulse shaping: uses shaping (evidence: `src/cortexforge/forge/radio/waveforms_digital.py`)
- Waveform generation → Modulation definitions: uses definitions (evidence: `src/cortexforge/forge/radio/waveforms_digital.py`)
- Receiver capture → GNU Radio recorder: records samples (evidence: `src/cortexforge/forge/radio/rx.py`)
- Receiver capture → Sync barrier client: registers and waits (evidence: `src/cortexforge/forge/radio/rx.py`)
- Transmitter → Sync barrier client: registers and waits (evidence: `src/cortexforge/forge/radio/tx.py`)
- Sync coordinator → Sync barrier server: runs barrier server (evidence: `src/cortexforge/forge/sync.py`)
- Sync barrier client → Sync barrier server: exchanges readiness
- Receiver capture → Power analysis: computes baseline (evidence: `src/cortexforge/forge/radio/rx.py`)
- Receiver capture → SigMF annotations: creates labels (evidence: `src/cortexforge/forge/radio/rx.py`)
- SigMF annotations → Power analysis: measures band power (evidence: `src/cortexforge/forge/utils/sigmf/sigmf_annotations.py`)
- Receiver capture → SigMF writer: writes metadata (evidence: `src/cortexforge/forge/radio/rx.py`)
- SigMF writer → SigMF recordings: writes recording files
- SigMF recordings → CorteXlab testbed: copies to shared storage
- Dataset user → Datasets CLI: lists or downloads (evidence: `src/cortexforge/datasets/main.py`)
- Datasets CLI → Dataset API: requests datasets (evidence: `src/cortexforge/datasets/main.py`)
- Dataset API → Local dataset access: uses local access (evidence: `src/cortexforge/datasets/api.py`)
- Dataset API → Dataset manifest: reads manifest (evidence: `src/cortexforge/datasets/api.py`)
- Local dataset access → Dataset manifest: uses manifest data (evidence: `src/cortexforge/datasets/local.py`)
- Local dataset access → Dataset files: installs datasets
