BLIS Design Documentation
This directory contains the public-facing design documentation for BLIS (Blackbox Inference Simulator). These pages explain BLIS's architecture, concepts, and configuration at the level needed to understand the system without reading source code.
Design Pages
Architecture & Internals
| Page |
Description |
| Cluster Architecture |
Multi-instance simulation: admission, routing, scorer composition, snapshot freshness, shared-clock event loop |
| Core Engine |
Single-instance DES engine: event queue, Step() phases, request lifecycle, batch formation, KV cache, latency models |
| Concepts & Glossary |
Definitions of BLIS-specific terminology |
| Configuration Reference |
All CLI flags, sub-config types, defaults.yaml behavior, workload modes |
| Roofline Estimation |
Analytical GPU step time estimation without training data |
For Contributors
| Page |
Description |
| Extension Recipes |
Step-by-step guides for adding policies, scorers, KV tiers, trace records, and metrics |
| Engineering Standards |
Antipattern rules (R1-R20), system invariants (INV-1 through INV-8), BDD/TDD principles |
| Process Workflows |
PR workflow, design document process, hypothesis experiment protocol |
Diagrams
| Diagram |
Description |
 |
End-to-end cluster pipeline: request arrival through metrics output |
 |
Request state machine: states, transitions, and metric recording points |
 |
DES event loop: min-heap queue, clock advancement, Step() decomposition |
 |
Weighted scorer composition: per-scorer normalization, weight multiplication, argmax selection |
Reading Order
For newcomers to BLIS:
- Start with Concepts & Glossary to learn BLIS-specific terminology
- Read Core Engine to understand the DES architecture and single-instance simulation
- Read Cluster Architecture to understand multi-instance orchestration
- Consult Configuration Reference when running experiments
- See Extension Recipes when adding new policies or features