# jeremyfrc/operationniobium_lab architecture

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

## Overview

OperationNiobium_Lab is a mixed repository of transformer and paged-KV inference kernels alongside CS149 coursework and kernel-challenge materials; its README does not describe a single end-user product. The clearest runtime workflow is a caller providing prompt token IDs to transformer generation, which runs decoder layers and returns generated IDs. Transformer internals and paged-cache management are represented separately where integration is not evidenced. The coursework branches are independent exercises, not stages in that workflow. Connections are limited to relationships visible in excerpts or the source index; unsampled implementation details are not inferred.

Main entry points: [`kernels/models/transformer/src/transformer.cpp`](https://github.com/jeremyfrc/operationniobium_lab/blob/master/kernels/models/transformer/src/transformer.cpp) (Decoder Stack), [`kernels/models/transformer/src/attention.cpp`](https://github.com/jeremyfrc/operationniobium_lab/blob/master/kernels/models/transformer/src/attention.cpp) (Attention), [`lectures/cs149/asst5-kernels/src/main.rs`](https://github.com/jeremyfrc/operationniobium_lab/blob/master/lectures/cs149/asst5-kernels/src/main.rs) (Challenge Application), [`kernels/paged_kv/src/sequence_manager.cpp`](https://github.com/jeremyfrc/operationniobium_lab/blob/master/kernels/paged_kv/src/sequence_manager.cpp) (Sequence Capacity)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_transformer["Transformer Inference"]
  node_generation["Autoregressive Generation<br/>[transformer.cpp]"]
  node_decoder["Decoder Stack<br/>[transformer.cpp]"]
  node_attention["Attention<br/>[attention.cpp]"]
  node_tensor["Tensor Storage<br/>[tensor.cpp]"]
  node_tensor_ops["Tensor Operations<br/>[ops.cpp]"]
  node_rope["RoPE Encoding<br/>[rope.cpp]"]
  node_feed_forward["SwiGLU Feed-Forward<br/>[swiglu.cpp]"]
  node_normalization["RMS Normalization<br/>[rmsnorm.cpp]"]
end

subgraph group_cache["Paged KV Cache"]
  node_paged_attention["Paged Attention"]
  node_paged_forward["Paged Forward Pass<br/>[forward_paged.cpp]"]
  node_sequence_capacity["Sequence Capacity"]
  node_block_table["Block Table<br/>[block_table.cpp]"]
  node_kv_store["Paged KV Store<br/>[paged_kv_cache.cpp]"]
end

subgraph group_coursework["CS149 Coursework"]
  node_vector_exercise["Vector Intrinsics<br/>[main.cpp]"]
  node_mandelbrot_exercise["ISPC Mandelbrot<br/>[main.cpp]"]
  node_renderer["Circle Renderer<br/>[main.cpp]"]
  node_scan_exercise["Parallel Scan<br/>[main.cpp]"]
end

subgraph group_challenges["Kernel Challenges"]
  node_kernel_problems["Kernel Problems"]
  node_challenge_app["Challenge Application<br/>[main.rs]"]
  node_challenge_commands["Challenge Commands"]
  node_challenge_service["Challenge Service"]
  node_challenge_views["Challenge Views"]
end

node_caller(("Model Caller"))

node_caller -.->|"provides prompt"| node_generation
node_generation -->|"runs decoding"| node_decoder
node_decoder -->|"calls attention"| node_attention
node_decoder -->|"calls feed-forward"| node_feed_forward
node_decoder -->|"calls normalization"| node_normalization
node_attention -->|"calls operations"| node_tensor_ops
node_attention -->|"applies encoding"| node_rope
node_attention -->|"uses tensors"| node_tensor
node_sequence_capacity -->|"reserves capacity"| node_block_table
node_sequence_capacity -->|"advances length"| node_block_table
node_paged_attention -.->|"uses KV cache"| node_kv_store
node_paged_forward -.->|"dispatches attention"| node_paged_attention
node_vector_exercise -.->|"independent exercise"| node_mandelbrot_exercise
node_challenge_app -.->|"imports commands"| node_challenge_commands
node_challenge_app -.->|"imports service"| node_challenge_service
node_challenge_app -.->|"imports views"| node_challenge_views

click node_generation "https://github.com/jeremyfrc/operationniobium_lab/blob/master/kernels/models/transformer/src/transformer.cpp"
click node_decoder "https://github.com/jeremyfrc/operationniobium_lab/blob/master/kernels/models/transformer/src/transformer.cpp"
click node_attention "https://github.com/jeremyfrc/operationniobium_lab/blob/master/kernels/models/transformer/src/attention.cpp"
click node_tensor "https://github.com/jeremyfrc/operationniobium_lab/blob/master/kernels/models/transformer/src/tensor.cpp"
click node_tensor_ops "https://github.com/jeremyfrc/operationniobium_lab/blob/master/kernels/models/transformer/src/ops.cpp"
click node_rope "https://github.com/jeremyfrc/operationniobium_lab/blob/master/kernels/models/transformer/src/rope.cpp"
click node_feed_forward "https://github.com/jeremyfrc/operationniobium_lab/blob/master/kernels/models/transformer/src/swiglu.cpp"
click node_normalization "https://github.com/jeremyfrc/operationniobium_lab/blob/master/kernels/models/transformer/src/rmsnorm.cpp"
click node_paged_attention "https://github.com/jeremyfrc/operationniobium_lab/blob/master/kernels/models/transformer/src/attention_paged.cpp"
click node_paged_forward "https://github.com/jeremyfrc/operationniobium_lab/blob/master/kernels/models/transformer/src/forward_paged.cpp"
click node_sequence_capacity "https://github.com/jeremyfrc/operationniobium_lab/blob/master/kernels/paged_kv/src/sequence_manager.cpp"
click node_block_table "https://github.com/jeremyfrc/operationniobium_lab/blob/master/kernels/paged_kv/src/block_table.cpp"
click node_kv_store "https://github.com/jeremyfrc/operationniobium_lab/blob/master/kernels/paged_kv/src/paged_kv_cache.cpp"
click node_vector_exercise "https://github.com/jeremyfrc/operationniobium_lab/blob/master/lectures/cs149/asst1/prog2_vecintrin/main.cpp"
click node_mandelbrot_exercise "https://github.com/jeremyfrc/operationniobium_lab/blob/master/lectures/cs149/asst1/prog3_mandelbrot_ispc/main.cpp"
click node_renderer "https://github.com/jeremyfrc/operationniobium_lab/blob/master/lectures/cs149/asst3/render/main.cpp"
click node_scan_exercise "https://github.com/jeremyfrc/operationniobium_lab/blob/master/lectures/cs149/asst3/scan/main.cpp"
click node_kernel_problems "https://github.com/jeremyfrc/operationniobium_lab/tree/master/lectures/cs149/asst5-kernels/problems"
click node_challenge_app "https://github.com/jeremyfrc/operationniobium_lab/blob/master/lectures/cs149/asst5-kernels/src/main.rs"
click node_challenge_commands "https://github.com/jeremyfrc/operationniobium_lab/tree/master/lectures/cs149/asst5-kernels/src/cmd"
click node_challenge_service "https://github.com/jeremyfrc/operationniobium_lab/tree/master/lectures/cs149/asst5-kernels/src/service"
click node_challenge_views "https://github.com/jeremyfrc/operationniobium_lab/tree/master/lectures/cs149/asst5-kernels/src/views"

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_generation,node_decoder,node_attention,node_tensor,node_tensor_ops,node_rope,node_feed_forward,node_normalization toneBlue
class node_paged_attention,node_paged_forward,node_sequence_capacity,node_block_table,node_kv_store toneAmber
class node_vector_exercise,node_mandelbrot_exercise,node_renderer,node_scan_exercise toneMint
class node_kernel_problems,node_challenge_app,node_challenge_commands,node_challenge_service,node_challenge_views toneRose
class node_caller toneIndigo
```

## Components

### Transformer Inference

- [Autoregressive Generation](https://github.com/jeremyfrc/operationniobium_lab/blob/master/kernels/models/transformer/src/transformer.cpp): `kernels/models/transformer/src/transformer.cpp`
- [Decoder Stack](https://github.com/jeremyfrc/operationniobium_lab/blob/master/kernels/models/transformer/src/transformer.cpp): `kernels/models/transformer/src/transformer.cpp`
- [Attention](https://github.com/jeremyfrc/operationniobium_lab/blob/master/kernels/models/transformer/src/attention.cpp): `kernels/models/transformer/src/attention.cpp`
- [Tensor Storage](https://github.com/jeremyfrc/operationniobium_lab/blob/master/kernels/models/transformer/src/tensor.cpp): `kernels/models/transformer/src/tensor.cpp`
- [Tensor Operations](https://github.com/jeremyfrc/operationniobium_lab/blob/master/kernels/models/transformer/src/ops.cpp): `kernels/models/transformer/src/ops.cpp`
- [RoPE Encoding](https://github.com/jeremyfrc/operationniobium_lab/blob/master/kernels/models/transformer/src/rope.cpp): `kernels/models/transformer/src/rope.cpp`
- [SwiGLU Feed-Forward](https://github.com/jeremyfrc/operationniobium_lab/blob/master/kernels/models/transformer/src/swiglu.cpp): `kernels/models/transformer/src/swiglu.cpp`
- [RMS Normalization](https://github.com/jeremyfrc/operationniobium_lab/blob/master/kernels/models/transformer/src/rmsnorm.cpp): `kernels/models/transformer/src/rmsnorm.cpp`

### Paged KV Cache

- [Paged Attention](https://github.com/jeremyfrc/operationniobium_lab/blob/master/kernels/models/transformer/src/attention_paged.cpp): `kernels/models/transformer/src/attention_paged.cpp`
- [Paged Forward Pass](https://github.com/jeremyfrc/operationniobium_lab/blob/master/kernels/models/transformer/src/forward_paged.cpp): `kernels/models/transformer/src/forward_paged.cpp`
- [Sequence Capacity](https://github.com/jeremyfrc/operationniobium_lab/blob/master/kernels/paged_kv/src/sequence_manager.cpp): `kernels/paged_kv/src/sequence_manager.cpp`
- [Block Table](https://github.com/jeremyfrc/operationniobium_lab/blob/master/kernels/paged_kv/src/block_table.cpp): `kernels/paged_kv/src/block_table.cpp`
- [Paged KV Store](https://github.com/jeremyfrc/operationniobium_lab/blob/master/kernels/paged_kv/src/paged_kv_cache.cpp): `kernels/paged_kv/src/paged_kv_cache.cpp`

### CS149 Coursework

- [Vector Intrinsics](https://github.com/jeremyfrc/operationniobium_lab/blob/master/lectures/cs149/asst1/prog2_vecintrin/main.cpp): `lectures/cs149/asst1/prog2_vecintrin/main.cpp`
- [ISPC Mandelbrot](https://github.com/jeremyfrc/operationniobium_lab/blob/master/lectures/cs149/asst1/prog3_mandelbrot_ispc/main.cpp): `lectures/cs149/asst1/prog3_mandelbrot_ispc/main.cpp`
- [Circle Renderer](https://github.com/jeremyfrc/operationniobium_lab/blob/master/lectures/cs149/asst3/render/main.cpp): `lectures/cs149/asst3/render/main.cpp`
- [Parallel Scan](https://github.com/jeremyfrc/operationniobium_lab/blob/master/lectures/cs149/asst3/scan/main.cpp): `lectures/cs149/asst3/scan/main.cpp`

### Kernel Challenges

- [Kernel Problems](https://github.com/jeremyfrc/operationniobium_lab/tree/master/lectures/cs149/asst5-kernels/problems): `lectures/cs149/asst5-kernels/problems`
- [Challenge Application](https://github.com/jeremyfrc/operationniobium_lab/blob/master/lectures/cs149/asst5-kernels/src/main.rs): `lectures/cs149/asst5-kernels/src/main.rs`
- [Challenge Commands](https://github.com/jeremyfrc/operationniobium_lab/tree/master/lectures/cs149/asst5-kernels/src/cmd): `lectures/cs149/asst5-kernels/src/cmd`
- [Challenge Service](https://github.com/jeremyfrc/operationniobium_lab/tree/master/lectures/cs149/asst5-kernels/src/service): `lectures/cs149/asst5-kernels/src/service`
- [Challenge Views](https://github.com/jeremyfrc/operationniobium_lab/tree/master/lectures/cs149/asst5-kernels/src/views): `lectures/cs149/asst5-kernels/src/views`

### Other components

- **Model Caller**

## Connections

- Model Caller → Autoregressive Generation: provides prompt
- Autoregressive Generation → Decoder Stack: runs decoding (evidence: `kernels/models/transformer/src/transformer.cpp`)
- Decoder Stack → Attention: calls attention (evidence: `kernels/models/transformer/src/transformer.cpp`)
- Decoder Stack → SwiGLU Feed-Forward: calls feed-forward (evidence: `kernels/models/transformer/src/transformer.cpp`)
- Decoder Stack → RMS Normalization: calls normalization (evidence: `kernels/models/transformer/src/transformer.cpp`)
- Attention → Tensor Operations: calls operations (evidence: `kernels/models/transformer/src/attention.cpp`)
- Attention → RoPE Encoding: applies encoding (evidence: `kernels/models/transformer/src/attention.cpp`)
- Attention → Tensor Storage: uses tensors (evidence: `kernels/models/transformer/src/attention.cpp`)
- Sequence Capacity → Block Table: reserves capacity (evidence: `kernels/paged_kv/src/sequence_manager.cpp`)
- Sequence Capacity → Block Table: advances length (evidence: `kernels/paged_kv/src/sequence_manager.cpp`)
- Paged Attention → Paged KV Store: uses KV cache
- Paged Forward Pass → Paged Attention: dispatches attention
- Vector Intrinsics → ISPC Mandelbrot: independent exercise
- Challenge Application → Challenge Commands: imports commands (evidence: `lectures/cs149/asst5-kernels/src/main.rs`)
- Challenge Application → Challenge Service: imports service (evidence: `lectures/cs149/asst5-kernels/src/main.rs`)
- Challenge Application → Challenge Views: imports views (evidence: `lectures/cs149/asst5-kernels/src/main.rs`)
