# itxprashant/csot-26-low-latency architecture

> Architecture diagram of the GitHub repository itxprashant/csot-26-low-latency, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/itxprashant/csot-26-low-latency
- Repository: https://github.com/itxprashant/csot-26-low-latency

## Overview

#### Purpose and Structure
This is a five-week Linux/C++20 low-latency systems curriculum culminating in a miniature quantitative-trading data path. Each week combines ordered instructional material with an independently judged implementation challenge. The repository is educational content plus CMake-built C++ project skeletons, not a deployed application.

Primary navigation starts at `README.md`, then each weekly overview such as `week-1/README.md` through `week-5/README.md`.

#### Week 1: Strategy Runner Foundation
Week 1 establishes memory/measurement concepts and the reference strategy boundary. The project defines histogram and strategy interfaces for a runner that consumes ticks, verifies decisions, and measures per-decision latency.

Key contracts and implementation boundary:
- `week-1/project/include/strategy.hpp`
- `week-1/project/include/histogram.hpp`
- `week-1/project/STRATEGY_SPEC.md`

The strategy implementation is intentionally replaceable; sample implementations illustrate correct versus incorrect behavior under the fixed spec.

#### Week 2: Cache Simulation Challenge
The first standalone ranked workload is a two-level cache simulator. A supplied harness reads memory traces, invokes the participant’s simulator API, and compares statistics/correctness while ranking runtime.

Flow: generated or fixture trace → harness → submitted cache simulator → cache statistics/output.

Core paths:
- `week-2/project/harness/main.cpp`
- `week-2/project/include/cache_sim.hpp`
- `week-2/project/CACHE_SPEC.md`

The judge-oriented boundary is source submission of the simulator, built with fixed compiler flags rather than dynamically loaded strategy artifacts.

#### Week 3: Parallel Tick Aggregation
This stage moves to parallel reduction of a tick stream into fixed per-symbol integer aggregates. Deterministic, partition-independent results let the harness detect correctness failures caused by data races while comparing wall-clock performance.

Flow: tick input → worker partitioning/reduction → deterministic aggregate table → JSON/reference comparison.

Core paths:
- `week-3/project/harness/main.cpp`
- `week-3/project/include/aggregate.hpp`
- `week-3/project/AGG_SPEC.md`

Its architectural concerns are worker ownership, synchronization avoidance, cache-line contention, and optional CPU affinity.

#### Week 4: Lock-Free Processing Pipeline
Week 4 composes producer and consumer stages around a participant-built SPSC ring buffer. The producer decodes a binary feed into ticks; the consumer executes the unchanged Week 1 strategy and emits orders. In-order delivery preserves deterministic strategy output despite concurrent execution.

Core paths:
- `week-4/project/harness/main.cpp`
- `week-4/project/include/pipeline.hpp`
- `week-4/project/PIPELINE_SPEC.md`

The key boundary is cross-thread handoff: atomics and acquire/release publication replace mutexes, while the strategy remains a single-consumer pure sequential stage.

#### Week 5: Network Gateway Capstone
The capstone exposes the pipeline to a connected loopback UDP feed. A gateway implementation owns nonblocking socket ingest and `epoll` readiness handling, decodes wire ticks, transfers them over the SPSC boundary to a pinned strategy thread, and returns acknowledgements to maintain lossless in-order flow.

Core paths:
- `week-5/project/harness/main.cpp`
- `week-5/project/include/gateway.hpp`
- `week-5/project/GATEWAY_SPEC.md`

End-to-end flow: UDP sender → kernel socket/`epoll` loop → decode → SPSC queue → strategy → order stream, with ACK-window feedback to the sender.

#### Build, Runtime, and Evaluation Boundaries
Every project uses CMake (`week-N/project/CMakeLists.txt`) and C++20 on Linux; concurrency challenges require pthread support. Linux-specific runtime mechanisms become material in later stages: scheduler affinity, atomics, UDP sockets, and `epoll`. Python generators produce fixture data, while plotting scripts visualize cache, scaling, or latency results; they are offline support rather than production dependencies.

Specifications are frozen per week, harnesses and hidden inputs are judge-owned, and participant-owned implementation files are the optimization surface. Performance ranking prioritizes correct deterministic output and latency/throughput, not trading profitability.

Main entry points: [`README.md`](https://github.com/itxprashant/csot-26-low-latency/blob/main/README.md) (Curriculum navigation), [`week-5/project/include/gateway.hpp`](https://github.com/itxprashant/csot-26-low-latency/blob/main/week-5/project/include/gateway.hpp) (UDP gateway API), [`week-1/project/include/strategy.hpp`](https://github.com/itxprashant/csot-26-low-latency/blob/main/week-1/project/include/strategy.hpp) (Strategy contract), [`week-4/project/include/pipeline.hpp`](https://github.com/itxprashant/csot-26-low-latency/blob/main/week-4/project/include/pipeline.hpp) (SPSC pipeline API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_w1["Week 1"]
  node_w1_overview["Week 1 overview<br/>module guide<br/>[README.md]"]
  node_strategy_contract["Strategy contract<br/>C++ interface<br/>[strategy.hpp]"]
  node_histogram_contract["Latency histogram<br/>C++ interface<br/>[histogram.hpp]"]
  node_strategy_spec["Strategy specification<br/>frozen spec<br/>[STRATEGY_SPEC.md]"]
end

subgraph group_w2["Week 2"]
  node_w2_overview["Week 2 overview<br/>module guide<br/>[README.md]"]
  node_cache_harness["Cache harness<br/>judge executable<br/>[main.cpp]"]
  node_cache_api["Cache simulator API<br/>C++ interface<br/>[cache_sim.hpp]"]
  node_cache_spec["Cache specification<br/>frozen spec<br/>[CACHE_SPEC.md]"]
end

subgraph group_w3["Week 3"]
  node_w3_overview["Week 3 overview<br/>module guide<br/>[README.md]"]
  node_aggregate_harness["Aggregation harness<br/>judge executable<br/>[main.cpp]"]
  node_aggregate_api["Aggregation API<br/>C++ interface<br/>[aggregate.hpp]"]
  node_aggregate_spec["Aggregation specification<br/>frozen spec<br/>[AGG_SPEC.md]"]
end

subgraph group_w4["Week 4"]
  node_w4_overview["Week 4 overview<br/>module guide<br/>[README.md]"]
  node_pipeline_harness["Pipeline harness<br/>judge executable<br/>[main.cpp]"]
  node_pipeline_api["SPSC pipeline API<br/>C++ interface<br/>[pipeline.hpp]"]
  node_pipeline_spec["Pipeline specification<br/>frozen spec<br/>[PIPELINE_SPEC.md]"]
end

subgraph group_w5["Week 5"]
  node_w5_overview["Week 5 overview<br/>module guide<br/>[README.md]"]
  node_gateway_harness["Gateway harness<br/>judge executable<br/>[main.cpp]"]
  node_gateway_api["UDP gateway API<br/>C++ interface<br/>[gateway.hpp]"]
  node_gateway_spec["Gateway specification<br/>frozen spec<br/>[GATEWAY_SPEC.md]"]
end

node_curriculum["Curriculum navigation<br/>documentation<br/>[README.md]"]

node_curriculum -->|"starts"| node_w1_overview
node_curriculum -->|"continues"| node_w2_overview
node_curriculum -->|"continues"| node_w3_overview
node_curriculum -->|"continues"| node_w4_overview
node_curriculum -->|"ends in capstone"| node_w5_overview
node_strategy_spec -->|"defines"| node_strategy_contract
node_strategy_contract -->|"records latency in"| node_histogram_contract
node_cache_harness -->|"invokes submission"| node_cache_api
node_cache_spec -->|"defines"| node_cache_api
node_aggregate_harness -->|"invokes submission"| node_aggregate_api
node_aggregate_spec -->|"defines"| node_aggregate_api
node_pipeline_harness -->|"drives"| node_pipeline_api
node_pipeline_spec -->|"defines ordering"| node_pipeline_api
node_pipeline_api -->|"single consumer runs"| node_strategy_contract
node_gateway_harness -->|"drives UDP feed"| node_gateway_api
node_gateway_spec -->|"defines"| node_gateway_api
node_gateway_api -->|"hands off decoded ticks"| node_pipeline_api
node_gateway_api -.->|"pins sequential strategy stage"| node_strategy_contract

click node_curriculum "https://github.com/itxprashant/csot-26-low-latency/blob/main/README.md"
click node_w1_overview "https://github.com/itxprashant/csot-26-low-latency/blob/main/week-1/README.md"
click node_strategy_contract "https://github.com/itxprashant/csot-26-low-latency/blob/main/week-1/project/include/strategy.hpp"
click node_histogram_contract "https://github.com/itxprashant/csot-26-low-latency/blob/main/week-1/project/include/histogram.hpp"
click node_strategy_spec "https://github.com/itxprashant/csot-26-low-latency/blob/main/week-1/project/STRATEGY_SPEC.md"
click node_w2_overview "https://github.com/itxprashant/csot-26-low-latency/blob/main/week-2/README.md"
click node_cache_harness "https://github.com/itxprashant/csot-26-low-latency/blob/main/week-2/project/harness/main.cpp"
click node_cache_api "https://github.com/itxprashant/csot-26-low-latency/blob/main/week-2/project/include/cache_sim.hpp"
click node_cache_spec "https://github.com/itxprashant/csot-26-low-latency/blob/main/week-2/project/CACHE_SPEC.md"
click node_w3_overview "https://github.com/itxprashant/csot-26-low-latency/blob/main/week-3/README.md"
click node_aggregate_harness "https://github.com/itxprashant/csot-26-low-latency/blob/main/week-3/project/harness/main.cpp"
click node_aggregate_api "https://github.com/itxprashant/csot-26-low-latency/blob/main/week-3/project/include/aggregate.hpp"
click node_aggregate_spec "https://github.com/itxprashant/csot-26-low-latency/blob/main/week-3/project/AGG_SPEC.md"
click node_w4_overview "https://github.com/itxprashant/csot-26-low-latency/blob/main/week-4/README.md"
click node_pipeline_harness "https://github.com/itxprashant/csot-26-low-latency/blob/main/week-4/project/harness/main.cpp"
click node_pipeline_api "https://github.com/itxprashant/csot-26-low-latency/blob/main/week-4/project/include/pipeline.hpp"
click node_pipeline_spec "https://github.com/itxprashant/csot-26-low-latency/blob/main/week-4/project/PIPELINE_SPEC.md"
click node_w5_overview "https://github.com/itxprashant/csot-26-low-latency/blob/main/week-5/README.md"
click node_gateway_harness "https://github.com/itxprashant/csot-26-low-latency/blob/main/week-5/project/harness/main.cpp"
click node_gateway_api "https://github.com/itxprashant/csot-26-low-latency/blob/main/week-5/project/include/gateway.hpp"
click node_gateway_spec "https://github.com/itxprashant/csot-26-low-latency/blob/main/week-5/project/GATEWAY_SPEC.md"

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_w1_overview,node_strategy_contract,node_histogram_contract,node_strategy_spec toneBlue
class node_w2_overview,node_cache_harness,node_cache_api,node_cache_spec toneAmber
class node_w3_overview,node_aggregate_harness,node_aggregate_api,node_aggregate_spec toneMint
class node_w4_overview,node_pipeline_harness,node_pipeline_api,node_pipeline_spec toneRose
class node_w5_overview,node_gateway_harness,node_gateway_api,node_gateway_spec toneIndigo
class node_curriculum toneNeutral
```

## Components

### Week 1

Strategy runner foundation.

- [Week 1 overview](https://github.com/itxprashant/csot-26-low-latency/blob/main/week-1/README.md): module guide · `week-1/README.md`
- [Strategy contract](https://github.com/itxprashant/csot-26-low-latency/blob/main/week-1/project/include/strategy.hpp): C++ interface · Replaceable strategy and latency histogram interfaces. · `week-1/project/include/strategy.hpp`
- [Latency histogram](https://github.com/itxprashant/csot-26-low-latency/blob/main/week-1/project/include/histogram.hpp): C++ interface · `week-1/project/include/histogram.hpp`
- [Strategy specification](https://github.com/itxprashant/csot-26-low-latency/blob/main/week-1/project/STRATEGY_SPEC.md): frozen spec · Defines runner decisions and verification behavior. · `week-1/project/STRATEGY_SPEC.md`

### Week 2

Cache simulation challenge.

- [Week 2 overview](https://github.com/itxprashant/csot-26-low-latency/blob/main/week-2/README.md): module guide · `week-2/README.md`
- [Cache harness](https://github.com/itxprashant/csot-26-low-latency/blob/main/week-2/project/harness/main.cpp): judge executable · Feeds traces, validates statistics, and measures runtime. · `week-2/project/harness/main.cpp`
- [Cache simulator API](https://github.com/itxprashant/csot-26-low-latency/blob/main/week-2/project/include/cache_sim.hpp): C++ interface · Participant implementation boundary. · `week-2/project/include/cache_sim.hpp`
- [Cache specification](https://github.com/itxprashant/csot-26-low-latency/blob/main/week-2/project/CACHE_SPEC.md): frozen spec · `week-2/project/CACHE_SPEC.md`

### Week 3

Parallel aggregation challenge.

- [Week 3 overview](https://github.com/itxprashant/csot-26-low-latency/blob/main/week-3/README.md): module guide · `week-3/README.md`
- [Aggregation harness](https://github.com/itxprashant/csot-26-low-latency/blob/main/week-3/project/harness/main.cpp): judge executable · Compares deterministic aggregates and wall-clock performance. · `week-3/project/harness/main.cpp`
- [Aggregation API](https://github.com/itxprashant/csot-26-low-latency/blob/main/week-3/project/include/aggregate.hpp): C++ interface · Parallel tick reduction boundary. · `week-3/project/include/aggregate.hpp`
- [Aggregation specification](https://github.com/itxprashant/csot-26-low-latency/blob/main/week-3/project/AGG_SPEC.md): frozen spec · `week-3/project/AGG_SPEC.md`

### Week 4

Lock-free pipeline challenge.

- [Week 4 overview](https://github.com/itxprashant/csot-26-low-latency/blob/main/week-4/README.md): module guide · `week-4/README.md`
- [Pipeline harness](https://github.com/itxprashant/csot-26-low-latency/blob/main/week-4/project/harness/main.cpp): judge executable · Exercises concurrent feed-to-order processing. · `week-4/project/harness/main.cpp`
- [SPSC pipeline API](https://github.com/itxprashant/csot-26-low-latency/blob/main/week-4/project/include/pipeline.hpp): C++ interface · Producer/consumer handoff with acquire-release publication. · `week-4/project/include/pipeline.hpp`
- [Pipeline specification](https://github.com/itxprashant/csot-26-low-latency/blob/main/week-4/project/PIPELINE_SPEC.md): frozen spec · `week-4/project/PIPELINE_SPEC.md`

### Week 5

Network gateway capstone.

- [Week 5 overview](https://github.com/itxprashant/csot-26-low-latency/blob/main/week-5/README.md): module guide · `week-5/README.md`
- [Gateway harness](https://github.com/itxprashant/csot-26-low-latency/blob/main/week-5/project/harness/main.cpp): judge executable · Drives the loopback UDP end-to-end workload. · `week-5/project/harness/main.cpp`
- [UDP gateway API](https://github.com/itxprashant/csot-26-low-latency/blob/main/week-5/project/include/gateway.hpp): C++ interface · Nonblocking epoll ingest, decode, SPSC transfer, and acknowledgements. · `week-5/project/include/gateway.hpp`
- [Gateway specification](https://github.com/itxprashant/csot-26-low-latency/blob/main/week-5/project/GATEWAY_SPEC.md): frozen spec · `week-5/project/GATEWAY_SPEC.md`

### Other components

- [Curriculum navigation](https://github.com/itxprashant/csot-26-low-latency/blob/main/README.md): documentation · Entry point linking the five ordered weekly modules. · `README.md`

## Connections

- Curriculum navigation → Week 1 overview: starts
- Curriculum navigation → Week 2 overview: continues
- Curriculum navigation → Week 3 overview: continues
- Curriculum navigation → Week 4 overview: continues
- Curriculum navigation → Week 5 overview: ends in capstone
- Strategy specification → Strategy contract: defines
- Strategy contract → Latency histogram: records latency in
- Cache harness → Cache simulator API: invokes submission
- Cache specification → Cache simulator API: defines
- Aggregation harness → Aggregation API: invokes submission
- Aggregation specification → Aggregation API: defines
- Pipeline harness → SPSC pipeline API: drives
- Pipeline specification → SPSC pipeline API: defines ordering
- SPSC pipeline API → Strategy contract: single consumer runs
- Gateway harness → UDP gateway API: drives UDP feed
- Gateway specification → UDP gateway API: defines
- UDP gateway API → SPSC pipeline API: hands off decoded ticks
- UDP gateway API → Strategy contract: pins sequential strategy stage