# hardy-c/adacomp architecture

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

- Interactive diagram: https://gitdiagram.com/hardy-c/adacomp
- Repository: https://github.com/hardy-c/adacomp

## Overview

AdaComp distributes MNIST stochastic-gradient training across workers and a parameter server, with an optional supervisor that periodically evaluates the shared model. The runtime starts by dispatching a node role; worker data is loaded locally, gradients are computed and compressed, and the PS applies updates while tracking staleness. The CNN and TensorFlow update operations are shared internal layers. The sampled code supports the principal paths below; connections between distributed processes are documented and visible in socket handling, but the full protocol is not independently traced end-to-end.

Main entry points: [`Worker.py`](https://github.com/hardy-c/adacomp/blob/master/Worker.py) (Worker trainer), [`PS.py`](https://github.com/hardy-c/adacomp/blob/master/PS.py) (Parameter server), [`Supervisor.py`](https://github.com/hardy-c/adacomp/blob/master/Supervisor.py) (Supervisor evaluator), [`main.py`](https://github.com/hardy-c/adacomp/blob/master/main.py) (Role dispatcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime roles"]
  node_entry["Role dispatcher<br/>[main.py]"]
  node_worker["Worker trainer<br/>[Worker.py]"]
  node_ps["Parameter server<br/>[PS.py]"]
  node_supervisor["Supervisor evaluator<br/>[Supervisor.py]"]
end

subgraph group_training["Training and model"]
  node_cnn["CNN model<br/>[Model_DNN.py]"]
  node_gradients["Gradient computation<br/>[Worker.py]"]
  node_sparse_update["Sparse updates<br/>[Tf_op.py]"]
  node_global_model["Shared parameters<br/>[Model_DNN.py]"]
end

subgraph group_coordination["Parameter coordination"]
  node_communication["Message encoding<br/>[Communication.py]"]
  node_staleness["Staleness scaling<br/>[PS.py]"]
end

subgraph group_evaluation["Data and evaluation"]
  node_mnist["MNIST input<br/>[mnist.py]"]
  node_metrics["Accuracy and loss<br/>[Supervisor.py]"]
end

node_operator(("Node operator"))

node_operator -->|"starts role"| node_entry
node_entry -->|"loads data"| node_mnist
node_entry -->|"dispatches"| node_worker
node_entry -->|"dispatches"| node_supervisor
node_entry -->|"dispatches"| node_ps
node_worker -->|"builds model"| node_cnn
node_worker -->|"computes gradients"| node_gradients
node_gradients -->|"encodes updates"| node_communication
node_worker -->|"requests parameters"| node_communication
node_worker -->|"sends updates"| node_ps
node_ps -->|"decodes messages"| node_communication
node_ps -->|"scales gradients"| node_staleness
node_ps -->|"builds update ops"| node_sparse_update
node_sparse_update -->|"updates parameters"| node_global_model
node_ps -->|"returns parameters"| node_worker
node_supervisor -->|"builds model"| node_cnn
node_supervisor -->|"requests parameters"| node_communication
node_supervisor -->|"builds fetch ops"| node_sparse_update
node_supervisor -->|"computes metrics"| node_metrics
node_mnist -->|"provides test batches"| node_supervisor

click node_entry "https://github.com/hardy-c/adacomp/blob/master/main.py"
click node_mnist "https://github.com/hardy-c/adacomp/blob/master/mnist.py"
click node_worker "https://github.com/hardy-c/adacomp/blob/master/Worker.py"
click node_cnn "https://github.com/hardy-c/adacomp/blob/master/Model_DNN.py"
click node_gradients "https://github.com/hardy-c/adacomp/blob/master/Worker.py"
click node_communication "https://github.com/hardy-c/adacomp/blob/master/Communication.py"
click node_ps "https://github.com/hardy-c/adacomp/blob/master/PS.py"
click node_staleness "https://github.com/hardy-c/adacomp/blob/master/PS.py"
click node_sparse_update "https://github.com/hardy-c/adacomp/blob/master/Tf_op.py"
click node_global_model "https://github.com/hardy-c/adacomp/blob/master/Model_DNN.py"
click node_supervisor "https://github.com/hardy-c/adacomp/blob/master/Supervisor.py"
click node_metrics "https://github.com/hardy-c/adacomp/blob/master/Supervisor.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_entry,node_worker,node_ps,node_supervisor toneBlue
class node_cnn,node_gradients,node_sparse_update,node_global_model toneAmber
class node_communication,node_staleness toneMint
class node_mnist,node_metrics toneRose
class node_operator toneIndigo
```

## Components

### Runtime roles

- [Role dispatcher](https://github.com/hardy-c/adacomp/blob/master/main.py): `main.py`
- [Worker trainer](https://github.com/hardy-c/adacomp/blob/master/Worker.py): `Worker.py`
- [Parameter server](https://github.com/hardy-c/adacomp/blob/master/PS.py): `PS.py`
- [Supervisor evaluator](https://github.com/hardy-c/adacomp/blob/master/Supervisor.py): `Supervisor.py`

### Training and model

- [CNN model](https://github.com/hardy-c/adacomp/blob/master/Model_DNN.py): `Model_DNN.py`
- [Gradient computation](https://github.com/hardy-c/adacomp/blob/master/Worker.py): `Worker.py`
- [Sparse updates](https://github.com/hardy-c/adacomp/blob/master/Tf_op.py): `Tf_op.py`
- [Shared parameters](https://github.com/hardy-c/adacomp/blob/master/Model_DNN.py): `Model_DNN.py`

### Parameter coordination

- [Message encoding](https://github.com/hardy-c/adacomp/blob/master/Communication.py): `Communication.py`
- [Staleness scaling](https://github.com/hardy-c/adacomp/blob/master/PS.py): `PS.py`

### Data and evaluation

- [MNIST input](https://github.com/hardy-c/adacomp/blob/master/mnist.py): `mnist.py`
- [Accuracy and loss](https://github.com/hardy-c/adacomp/blob/master/Supervisor.py): `Supervisor.py`

### Other components

- **Node operator**

## Connections

- Node operator → Role dispatcher: starts role (evidence: `README.md`)
- Role dispatcher → MNIST input: loads data (evidence: `main.py`)
- Role dispatcher → Worker trainer: dispatches (evidence: `main.py`)
- Role dispatcher → Supervisor evaluator: dispatches (evidence: `main.py`)
- Role dispatcher → Parameter server: dispatches (evidence: `main.py`)
- Worker trainer → CNN model: builds model (evidence: `Worker.py`)
- Worker trainer → Gradient computation: computes gradients (evidence: `Worker.py`)
- Gradient computation → Message encoding: encodes updates (evidence: `Worker.py`)
- Worker trainer → Message encoding: requests parameters (evidence: `Worker.py`)
- Worker trainer → Parameter server: sends updates (evidence: `README.md`)
- Parameter server → Message encoding: decodes messages (evidence: `PS.py`)
- Parameter server → Staleness scaling: scales gradients (evidence: `PS.py`)
- Parameter server → Sparse updates: builds update ops (evidence: `PS.py`)
- Sparse updates → Shared parameters: updates parameters (evidence: `Tf_op.py`)
- Parameter server → Worker trainer: returns parameters (evidence: `README.md`)
- Supervisor evaluator → CNN model: builds model (evidence: `Supervisor.py`)
- Supervisor evaluator → Message encoding: requests parameters (evidence: `Supervisor.py`)
- Supervisor evaluator → Sparse updates: builds fetch ops (evidence: `Supervisor.py`)
- Supervisor evaluator → Accuracy and loss: computes metrics (evidence: `Supervisor.py`)
- MNIST input → Supervisor evaluator: provides test batches (evidence: `main.py`)
