# samamabile/irontorch architecture

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

- Interactive diagram: https://gitdiagram.com/samamabile/irontorch
- Repository: https://github.com/samamabile/irontorch

## Overview

IronTorch is a C++ text-classification and next-token-prediction system that can train embeddings through NTP. The main workflow accepts text or labeled CSV data, builds BPE tokens, trains a CNN, and uses saved model/tokenizer files for classification or generation. The README documents the network variants and pretraining option; sampled code confirms the API, tokenizer, training, and inference responsibilities. Some training and architecture wiring is inferred from documented capabilities, so uncertain call paths are omitted.

Main entry points: [`model.cpp`](https://github.com/samamabile/irontorch/blob/main/model.cpp) (Model), [`train.cpp`](https://github.com/samamabile/irontorch/blob/main/train.cpp) (Trainer), [`inference.cpp`](https://github.com/samamabile/irontorch/blob/main/inference.cpp) (Inference), [`irontorch.cpp`](https://github.com/samamabile/irontorch/blob/main/irontorch.cpp) (IronTorch API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["API and inference"]
  node_api["CLI entry<br/>[api.cpp]"]
  node_facade["IronTorch API<br/>[irontorch.cpp]"]
  node_inference["Inference<br/>[inference.cpp]"]
end

subgraph group_text["Text preparation"]
  node_tokenizer["Dataset tokenizer<br/>[tokenizer.cpp]"]
  node_bpe["BPE tokenizer<br/>[bpe.cpp]"]
end

subgraph group_training["Training workflows"]
  node_trainer["Trainer<br/>[train.cpp]"]
  node_batcher["Batcher<br/>[batcher.cpp]"]
  node_optimizer["Optimizer<br/>[optimizer.hpp]"]
  node_loss["Loss functions<br/>[loss.cpp]"]
end

subgraph group_network["Neural network"]
  node_architecture["Architecture setup<br/>[arch.cpp]"]
  node_model["Model<br/>[model.cpp]"]
  node_embedding["Embedding layer<br/>[embedding.cpp]"]
  node_conv["Conv1D layer<br/>[conv1d.cpp]"]
  node_double_conv["Parallel Conv1D<br/>[doubleConv1d.cpp]"]
  node_activations["Activations<br/>[relu.cpp]"]
  node_pooling["Pooling<br/>[pool.cpp]"]
  node_dense["Dense layer<br/>[dense.cpp]"]
  node_heads["Output heads<br/>[sigmoid.cpp]"]
end

subgraph group_runtime["Numerical runtime"]
  node_matrix["Matrix operations<br/>[matrix.cpp]"]
end

node_user(("User"))
node_input_data["Text or CSV"]
node_model_files["Model and BPE files"]

node_user -->|"provides input"| node_api
node_input_data -->|"supplies data"| node_api
node_api -->|"dispatches"| node_facade
node_facade -->|"trains"| node_trainer
node_facade -->|"loads or predicts"| node_inference
node_trainer -->|"prepares tokens"| node_tokenizer
node_tokenizer -->|"fits and tokenizes"| node_bpe
node_trainer -->|"batches data"| node_batcher
node_trainer -->|"sets up layers"| node_architecture
node_architecture -->|"initializes"| node_model
node_trainer -->|"trains"| node_model
node_trainer -->|"computes loss"| node_loss
node_trainer -->|"updates parameters"| node_optimizer
node_model -->|"dispatches layers"| node_embedding
node_model -->|"dispatches layers"| node_double_conv
node_model -->|"dispatches layers"| node_conv
node_model -->|"dispatches layers"| node_activations
node_model -->|"dispatches layers"| node_pooling
node_model -->|"dispatches layers"| node_dense
node_model -->|"dispatches layers"| node_heads
node_embedding -->|"uses operations"| node_matrix
node_conv -->|"uses operations"| node_matrix
node_facade -->|"reads data"| node_input_data
node_trainer -->|"saves weights"| node_model_files
node_tokenizer -->|"saves BPE rules"| node_model_files
node_inference -->|"loads artifacts"| node_model_files
node_inference -->|"loads and tokenizes"| node_tokenizer
node_inference -->|"runs forward pass"| node_model
node_inference -->|"creates embedding"| node_embedding
node_inference -->|"returns prediction or text"| node_user

click node_api "https://github.com/samamabile/irontorch/blob/main/api.cpp"
click node_facade "https://github.com/samamabile/irontorch/blob/main/irontorch.cpp"
click node_inference "https://github.com/samamabile/irontorch/blob/main/inference.cpp"
click node_tokenizer "https://github.com/samamabile/irontorch/blob/main/tokenizer.cpp"
click node_bpe "https://github.com/samamabile/irontorch/blob/main/bpe.cpp"
click node_trainer "https://github.com/samamabile/irontorch/blob/main/train.cpp"
click node_batcher "https://github.com/samamabile/irontorch/blob/main/batcher.cpp"
click node_optimizer "https://github.com/samamabile/irontorch/blob/main/optimizer.hpp"
click node_loss "https://github.com/samamabile/irontorch/blob/main/loss.cpp"
click node_architecture "https://github.com/samamabile/irontorch/blob/main/arch.cpp"
click node_model "https://github.com/samamabile/irontorch/blob/main/model.cpp"
click node_embedding "https://github.com/samamabile/irontorch/blob/main/embedding.cpp"
click node_conv "https://github.com/samamabile/irontorch/blob/main/conv1d.cpp"
click node_double_conv "https://github.com/samamabile/irontorch/blob/main/doubleConv1d.cpp"
click node_activations "https://github.com/samamabile/irontorch/blob/main/relu.cpp"
click node_pooling "https://github.com/samamabile/irontorch/blob/main/pool.cpp"
click node_dense "https://github.com/samamabile/irontorch/blob/main/dense.cpp"
click node_heads "https://github.com/samamabile/irontorch/blob/main/sigmoid.cpp"
click node_matrix "https://github.com/samamabile/irontorch/blob/main/matrix.cpp"

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_api,node_facade,node_inference,node_user toneBlue
class node_tokenizer,node_bpe toneAmber
class node_trainer,node_batcher,node_optimizer,node_loss toneMint
class node_architecture,node_model,node_embedding,node_conv,node_double_conv,node_activations,node_pooling,node_dense,node_heads toneRose
class node_matrix,node_input_data,node_model_files toneIndigo
```

## Components

### API and inference

- [CLI entry](https://github.com/samamabile/irontorch/blob/main/api.cpp): `api.cpp`
- [IronTorch API](https://github.com/samamabile/irontorch/blob/main/irontorch.cpp): `irontorch.cpp`
- [Inference](https://github.com/samamabile/irontorch/blob/main/inference.cpp): `inference.cpp`

### Text preparation

- [Dataset tokenizer](https://github.com/samamabile/irontorch/blob/main/tokenizer.cpp): `tokenizer.cpp`
- [BPE tokenizer](https://github.com/samamabile/irontorch/blob/main/bpe.cpp): `bpe.cpp`

### Training workflows

- [Trainer](https://github.com/samamabile/irontorch/blob/main/train.cpp): `train.cpp`
- [Batcher](https://github.com/samamabile/irontorch/blob/main/batcher.cpp): `batcher.cpp`
- [Optimizer](https://github.com/samamabile/irontorch/blob/main/optimizer.hpp): `optimizer.hpp`
- [Loss functions](https://github.com/samamabile/irontorch/blob/main/loss.cpp): `loss.cpp`

### Neural network

- [Architecture setup](https://github.com/samamabile/irontorch/blob/main/arch.cpp): `arch.cpp`
- [Model](https://github.com/samamabile/irontorch/blob/main/model.cpp): `model.cpp`
- [Embedding layer](https://github.com/samamabile/irontorch/blob/main/embedding.cpp): `embedding.cpp`
- [Conv1D layer](https://github.com/samamabile/irontorch/blob/main/conv1d.cpp): `conv1d.cpp`
- [Parallel Conv1D](https://github.com/samamabile/irontorch/blob/main/doubleConv1d.cpp): `doubleConv1d.cpp`
- [Activations](https://github.com/samamabile/irontorch/blob/main/relu.cpp): `relu.cpp`
- [Pooling](https://github.com/samamabile/irontorch/blob/main/pool.cpp): `pool.cpp`
- [Dense layer](https://github.com/samamabile/irontorch/blob/main/dense.cpp): `dense.cpp`
- [Output heads](https://github.com/samamabile/irontorch/blob/main/sigmoid.cpp): `sigmoid.cpp`

### Numerical runtime

- [Matrix operations](https://github.com/samamabile/irontorch/blob/main/matrix.cpp): `matrix.cpp`

### Other components

- **User**
- **Text or CSV**
- **Model and BPE files**

## Connections

- User → CLI entry: provides input
- Text or CSV → CLI entry: supplies data
- CLI entry → IronTorch API: dispatches
- IronTorch API → Trainer: trains
- IronTorch API → Inference: loads or predicts
- Trainer → Dataset tokenizer: prepares tokens
- Dataset tokenizer → BPE tokenizer: fits and tokenizes
- Trainer → Batcher: batches data
- Trainer → Architecture setup: sets up layers
- Architecture setup → Model: initializes
- Trainer → Model: trains
- Trainer → Loss functions: computes loss
- Trainer → Optimizer: updates parameters
- Model → Embedding layer: dispatches layers
- Model → Parallel Conv1D: dispatches layers
- Model → Conv1D layer: dispatches layers
- Model → Activations: dispatches layers
- Model → Pooling: dispatches layers
- Model → Dense layer: dispatches layers
- Model → Output heads: dispatches layers
- Embedding layer → Matrix operations: uses operations
- Conv1D layer → Matrix operations: uses operations
- IronTorch API → Text or CSV: reads data
- Trainer → Model and BPE files: saves weights
- Dataset tokenizer → Model and BPE files: saves BPE rules
- Inference → Model and BPE files: loads artifacts
- Inference → Dataset tokenizer: loads and tokenizes
- Inference → Model: runs forward pass
- Inference → Embedding layer: creates embedding
- Inference → User: returns prediction or text