# Queries Per Second (QPS) — Full Technical Reference (`llms-full.txt`)

> Complete machine-readable reference for Queries Per Second — System Designer (https://queriespersecond.com), covering the simulation engine formulas, full 70+ module catalog with capacity/latency/cost defaults, SRE incident campaigns with telemetry probes and root-cause analyses, and Model Context Protocol (MCP) tool specifications.

---

## 1. Overview & Purpose

**Queries Per Second (QPS)** is an interactive system architecture simulator and SRE incident response workbench. It addresses two primary workflows:
1. **Sandbox Mode**: Engineers and AI agents construct distributed system diagrams from 70+ pre-calibrated cloud, database, caching, messaging, ML, and AI/agentic modules, then simulate live QPS traffic to identify saturation bottlenecks, tail latency (P95/P99), and hourly infrastructure cost.
2. **Campaign Mode**: Interactive production outage investigations where users probe live component telemetry, test falsifiable engineering hypotheses, execute immediate mitigations, and re-architect the system to meet strict SLA targets (P95 latency, success rate %, and $/hr cost).

---

## 2. Flow Simulation Engine (`FlowEngine`)

The simulation engine evaluates directed graphs of architecture components under a configurable ingress traffic load (measured in `req/s` or `QPS`):

- **Effective Node Capacity**: `effectiveCapacity = capacityPerInstance * quantity`
- **Node Load / Utilization**: `utilization = incomingQps / effectiveCapacity`
- **Health Status Thresholds**:
  - `OK` (Teal): Utilization `< 80%` (healthy headroom)
  - `WARNING` (Amber): Utilization `>= 80%` and `<= 100%` (approaching saturation, tail latency begins climbing)
  - `CRITICAL` (Crimson): Utilization `> 100%` (overloaded; requests are dropped and P95/P99 latency spikes nonlinearly)
- **Wire / Link Types**:
  - **Solid Line (`solid`)**: Synchronous / blocking RPC (`HTTPS`, `gRPC`, `SQL Pool`, `TCP`). Downstream latency and errors propagate directly to upstream callers.
  - **Dashed Line (`dashed`)**: Asynchronous / event-driven flow (`Kafka`, `SQS`, `Batch Export`, `Webhooks`). Decouples immediate caller latency via buffering/queues.

---

## 3. Complete Module Catalog (`MODULE_CATALOG`)

Below are all 76 system design modules across 14 categories with their default per-instance capacity (QPS), baseline P95 latency (ms), and relative hourly cost rate ($/hr per instance):

### 3.1 Clients
| Module | Category | Default Capacity (QPS) | Default P95 (ms) | Cost Rate ($/hr) | Keywords / Aliases |
| :--- | :--- | ---: | ---: | ---: | :--- |
| Android App | Client | 10,000 | 5 | $0.00 | mobile phone kotlin java |
| iOS App | Client | 10,000 | 5 | $0.00 | mobile iphone swift apple |
| Web App | Client | 10,000 | 5 | $0.00 | browser react nextjs frontend html |
| Desktop App | Client | 10,000 | 5 | $0.00 | electron tauri mac windows desktop |
| Mobile Web | Client | 10,000 | 5 | $0.00 | pwa safari chrome mobile browser |
| Smartwatch App | Client | 10,000 | 5 | $0.00 | wearos watchos apple watch iot |
| Smart TV App | Client | 10,000 | 5 | $0.00 | appletv androidtv roku firetv streaming client |
| VR/AR App | Client | 10,000 | 5 | $0.00 | quest vision pro unity spatial metaverse |
| CLI Tool | Client | 10,000 | 5 | $0.00 | terminal command line developer tool |
| Browser Extension | Client | 10,000 | 5 | $0.00 | plugin addon chrome manifest v3 |

### 3.2 Gateways & Traffic
| Module | Category | Default Capacity (QPS) | Default P95 (ms) | Cost Rate ($/hr) | Keywords / Aliases |
| :--- | :--- | ---: | ---: | ---: | :--- |
| API Gateway | Gateway | 5,000 | 8 | $0.30 | kong envoy ingress api router reverse proxy |
| Load Balancer | Gateway | 10,000 | 4 | $0.25 | alb nlb haproxy nginx traffic distributor |
| GraphQL Gateway | Gateway | 4,000 | 12 | $0.35 | apollo federation schema graphql mesh |
| Service Mesh Ingress | Gateway | 6,000 | 7 | $0.40 | istio linkerd sidecar proxy mesh |
| Reverse Proxy (Nginx/Envoy) | Gateway | 8,000 | 5 | $0.25 | caddy nginx envoy ingress edge |

### 3.3 Services & Compute
| Module | Category | Default Capacity (QPS) | Default P95 (ms) | Cost Rate ($/hr) | Keywords / Aliases |
| :--- | :--- | ---: | ---: | ---: | :--- |
| Microservice | Service | 2,000 | 20 | $0.42 | backend api node go rust python service |
| Lambda / Serverless | Service | 3,000 | 35 | $0.20 | serverless faas cloud function edge |
| Batch Job | Service | 1,500 | 45 | $0.30 | cron worker async task consumer |
| Cron Worker | Service | 1,500 | 50 | $0.28 | scheduler background job periodic task |
| Monolith Service | Service | 3,500 | 28 | $0.80 | monolith legacy core backend all-in-one |
| Edge Function | Service | 6,000 | 12 | $0.18 | cloudflare workers vercel edge middleware |
| BFF (Backend For Frontend) | Service | 2,500 | 18 | $0.38 | frontend api gateway adapter client bff |

### 3.4 Databases
| Module | Category | Default Capacity (QPS) | Default P95 (ms) | Cost Rate ($/hr) | Keywords / Aliases |
| :--- | :--- | ---: | ---: | ---: | :--- |
| RDS | Database | 2,000 | 30 | $1.50 | relational aws sql database postgres mysql |
| DynamoDB | Database | 5,000 | 10 | $0.90 | nosql key-value document aws managed |
| PostgreSQL | Database | 1,800 | 35 | $1.60 | relational rds sql postgres acid |
| MySQL | Database | 2,000 | 30 | $1.50 | relational sql innodb rds database |
| MongoDB | Database | 3,000 | 22 | $1.10 | document json nosql atlas database |
| Cassandra | Database | 7,000 | 15 | $1.80 | wide-column distributed scylla nosql bigdata |
| Neo4j (Graph DB) | Database | 1,500 | 40 | $1.40 | graph database cypher relationship network |
| ElasticSearch | Database | 2,200 | 40 | $1.20 | search lucene fulltext opensearch analytics |
| Snowflake | Database | 4,000 | 150 | $2.50 | data warehouse olap analytics sql cloud |
| BigQuery | Database | 4,500 | 120 | $2.20 | data warehouse google gcp analytics sql |

### 3.5 Caches
| Module | Category | Default Capacity (QPS) | Default P95 (ms) | Cost Rate ($/hr) | Keywords / Aliases |
| :--- | :--- | ---: | ---: | ---: | :--- |
| Redis | Cache | 8,000 | 3 | $0.38 | in-memory key-value cache fast session cluster |
| Memcached | Cache | 10,000 | 3 | $0.35 | lru in-memory simple key-value cache |
| ElastiCache | Cache | 9,000 | 4 | $0.45 | aws managed redis memcached cluster |
| CDN | Cache | 25,000 | 2 | $0.15 | cloudflare cloudfront fastly edge cache static assets |
| Application Cache | Cache | 15,000 | 1 | $0.10 | in-process memory lru guava caffeine |
| Hazelcast | Cache | 7,500 | 5 | $0.50 | in-memory data grid distributed cache imdg |
| In-Memory LRU Cache | Cache | 20,000 | 1 | $0.05 | local memory eviction lru cache |

### 3.6 Queues
| Module | Category | Default Capacity (QPS) | Default P95 (ms) | Cost Rate ($/hr) | Keywords / Aliases |
| :--- | :--- | ---: | ---: | ---: | :--- |
| SQS | Queue | 5,000 | 10 | $0.30 | aws message queue fifo async buffer |
| RabbitMQ | Queue | 6,000 | 8 | $0.35 | amqp message broker exchange topic routing |
| Apache Kafka | Queue | 12,000 | 8 | $0.75 | event streaming log topic partition consumer group |
| ActiveMQ | Queue | 4,000 | 12 | $0.32 | jms amqp message broker enterprise queue |
| Redis Queue | Queue | 7,000 | 5 | $0.38 | rpush lpop streams redis list queue bullmq |
| Google Pub/Sub | Queue | 8,000 | 9 | $0.40 | gcp pubsub topic subscription message queue |
| Azure Service Bus | Queue | 5,500 | 10 | $0.42 | microsoft azure enterprise message broker queue |

### 3.7 Streams
| Module | Category | Default Capacity (QPS) | Default P95 (ms) | Cost Rate ($/hr) | Keywords / Aliases |
| :--- | :--- | ---: | ---: | ---: | :--- |
| Kinesis | Stream | 10,000 | 12 | $0.60 | aws data stream shard real-time analytics |
| Apache Kafka Streams | Stream | 9,000 | 14 | $0.70 | kstreams stateful processing real-time windowing |
| Apache Flink | Stream | 11,000 | 10 | $0.85 | stateful stream processing low latency exactly-once |
| Apache Spark Streaming | Stream | 8,000 | 45 | $0.90 | microbatch spark streaming bigdata processing |
| Event Hub | Stream | 9,500 | 11 | $0.55 | azure event ingest real-time stream |
| Materialized Streams | Stream | 7,000 | 16 | $0.75 | materialize ksqldb real-time materialized views |

### 3.8 Storage
| Module | Category | Default Capacity (QPS) | Default P95 (ms) | Cost Rate ($/hr) | Keywords / Aliases |
| :--- | :--- | ---: | ---: | ---: | :--- |
| S3 Bucket | Storage | 6,000 | 25 | $0.12 | aws object store blob files media |
| Blob Storage | Storage | 5,500 | 28 | $0.12 | azure blob container object storage files |
| GCS | Storage | 6,000 | 25 | $0.12 | google cloud storage bucket object store |
| Local Disk Storage | Storage | 12,000 | 3 | $0.20 | nvme ssd attached disk local volume |
| NAS / NFS | Storage | 3,500 | 18 | $0.30 | network file system shared mount efs |

### 3.9 Observability
| Module | Category | Default Capacity (QPS) | Default P95 (ms) | Cost Rate ($/hr) | Keywords / Aliases |
| :--- | :--- | ---: | ---: | ---: | :--- |
| NewRelic | Observability | 10,000 | 15 | $0.20 | apm monitoring traces metrics alerts |
| Datadog | Observability | 12,000 | 12 | $0.25 | monitoring logs traces metrics agent |
| Prometheus | Observability | 15,000 | 8 | $0.15 | metrics time series scraper promql |
| Grafana | Observability | 5,000 | 20 | $0.10 | dashboard visualization telemetry alerts |
| Jaeger Tracing | Observability | 8,000 | 14 | $0.18 | distributed tracing spans open-telemetry otel |
| OpenTelemetry Collector | Observability | 14,000 | 6 | $0.15 | otel collector exporter pipeline receiver |

### 3.10 Security
| Module | Category | Default Capacity (QPS) | Default P95 (ms) | Cost Rate ($/hr) | Keywords / Aliases |
| :--- | :--- | ---: | ---: | ---: | :--- |
| IAM | Security | 8,000 | 8 | $0.10 | identity access management auth rbac policies |
| Cognito / Auth0 | Security | 4,000 | 22 | $0.25 | authentication jwt sso oauth user pool |
| KMS Encryption | Security | 7,000 | 10 | $0.20 | key management encryption envelope security |
| WAF | Security | 12,000 | 5 | $0.35 | web application firewall ddos bot protection |
| OAuth Server | Security | 4,500 | 18 | $0.25 | authorization server token issuer oauth2 oidc |
| Secrets Manager | Security | 5,000 | 15 | $0.15 | vault credentials keys rotation secret |
| Certificate Manager | Security | 6,000 | 12 | $0.10 | tls ssl certs https automation |

### 3.11 DevOps & Infrastructure
| Module | Category | Default Capacity (QPS) | Default P95 (ms) | Cost Rate ($/hr) | Keywords / Aliases |
| :--- | :--- | ---: | ---: | ---: | :--- |
| Kubernetes Cluster | DevOps | 10,000 | 15 | $1.20 | k8s pods nodes orchestration container |
| EC2 Instance | DevOps | 4,000 | 20 | $0.60 | vm virtual machine compute host aws |
| Docker Container | DevOps | 3,500 | 20 | $0.35 | container docker image cgroup runtime |
| ArgoCD Pipeline | DevOps | 2,000 | 45 | $0.20 | gitops deployment k8s continuous delivery |
| Jenkins Pipeline | DevOps | 1,800 | 50 | $0.25 | ci cd build automated pipeline |
| GitHub Actions | DevOps | 2,500 | 40 | $0.20 | ci cd workflows runner automation |
| Terraform Infrastructure | DevOps | 2,000 | 60 | $0.15 | iac infrastructure as code state hcl |

### 3.12 Integrations
| Module | Category | Default Capacity (QPS) | Default P95 (ms) | Cost Rate ($/hr) | Keywords / Aliases |
| :--- | :--- | ---: | ---: | ---: | :--- |
| Stripe Payment Gateway | Integration | 3,000 | 150 | $0.60 | payments checkout charges billing stripe |
| Plaid | Integration | 2,000 | 180 | $0.50 | banking ach financial api account verification |
| Twilio | Integration | 4,000 | 100 | $0.40 | sms voice communications 2fa otp messaging |
| Salesforce | Integration | 1,500 | 220 | $0.70 | crm enterprise customer data sync api |
| Webhook Endpoint | Integration | 5,000 | 25 | $0.20 | http callback incoming webhook event handler |

### 3.13 AI & Agentic Systems
| Module | Category | Default Capacity (QPS) | Default P95 (ms) | Cost Rate ($/hr) | Keywords / Aliases |
| :--- | :--- | ---: | ---: | ---: | :--- |
| LLM Model (OpenAI/Llama/Mixtral) | Agentic | 300 | 800 | $4.50 | gpt-4o claude gemini foundation model inference ai |
| Agent Planner | Agentic | 400 | 600 | $2.20 | task decomposition plan react step reasoning |
| Agent Orchestrator | Agentic | 600 | 350 | $1.80 | multi-agent graph workflow supervisor conductor |
| Tool Adapter / Tool Bridge | Agentic | 1,500 | 90 | $0.80 | mcp function calling tools execution api bridge |
| Reasoning Engine | Agentic | 500 | 500 | $2.00 | chain of thought tree of thoughts logic deduction |
| Memory Store | Agentic | 3,000 | 15 | $0.70 | episodic semantic long-term memory mem0 scratchpad |
| Vector Database | Agentic | 2,500 | 45 | $1.40 | pinecone milvus qdrant pgvector embeddings search |
| Embedding Model | Agentic | 3,500 | 35 | $0.80 | text-embedding-3 ada vectorizer semantic encoder |
| Retrieval Engine (RAG) | Agentic | 1,200 | 120 | $1.50 | rag hybrid search reranker context injection chunks |
| Function Calling Engine | Agentic | 2,000 | 60 | $0.90 | schema parser tool invocation structured output |
| Self-Reflection Component | Agentic | 500 | 400 | $1.60 | critic self-correction loop verification refinement |
| Evaluator Agent | Agentic | 600 | 350 | $1.50 | judge grading scoring rubric assessment |
| Safety + Guardrail Layer | Agentic | 4,000 | 25 | $0.50 | content filter pii redactor nemo moderation guard |
| Prompt Router | Agentic | 3,500 | 30 | $0.60 | intent classifier model routing semantic triage gateway |
| Supervisor Agent | Agentic | 700 | 300 | $1.70 | coordinator manager consensus director agent |
| Simulation / Sandbox Engine | Agentic | 800 | 250 | $1.20 | code execution repl virtual environment docker |

### 3.14 Machine Learning
| Module | Category | Default Capacity (QPS) | Default P95 (ms) | Cost Rate ($/hr) | Keywords / Aliases |
| :--- | :--- | ---: | ---: | ---: | :--- |
| Feature Store | ML | 4,000 | 18 | $1.10 | feast hopsworks feature registry online offline features |
| Training Pipeline | ML | 1,000 | 300 | $2.80 | kubeflow sagemaker model training gpu distributed |
| ML Inference Service | ML | 2,500 | 55 | $1.60 | triton vllm torchserve model serving endpoint |
| Model Registry | ML | 3,000 | 25 | $0.60 | mlflow weights biases artifacts versioning |
| Model Monitoring | ML | 5,000 | 20 | $0.50 | drift detection evidently quality alerts latency |

---

## 4. Detailed SRE Incident Campaigns & Case Studies

### Campaign 1: The Midnight Outage (`campaign-midnight-outage`)
- **Theme**: Resource Contention & Feedback Loops
- **Difficulty**: INTERMEDIATE

#### Episode 01: The Phantom Healthy System (`ep1-connection-pool-starvation`)
- **Symptom**: Customers report checkout timeouts and 504 gateway errors (58% failure rate, P99 latency 8,420 ms) while App CPU is 12%, DB CPU is 24%, and `/health` returns `200 OK`.
- **Offered Load**: 2,400 req/s
- **Telemetry Findings**:
  - `checkout_service`: 498/500 threads in `WAITING` state blocked on acquiring a DB connection lease.
  - `db_pool`: 98/100 connections active, 743 waiting requests, 8.4s P99 lease acquisition time. Tenant #4182's 3-year historical CSV export holds 70% (69 connections) of the shared pool.
  - `client`: 1,450 req/s aggressive retries with no exponential backoff or jitter.
- **Root Cause**: Shared Connection Pool Starvation & Noisy Neighbor compounded by an unjittered client retry storm.
- **Emergency Mitigation (1 min)**: Cancel/throttle the Tenant Export Job and shed non-critical reporting load, freeing 69 connections and restoring checkout success from 41.2% to 99.8%.
- **Architectural Prevention**: Bulkhead Pattern & Workload Isolation — separate transactional checkout pools from background reporting pools, route exports to a Read Replica, and enforce exponential backoff with randomized jitter.
- **SLA Targets**: Max P95 `<= 180 ms`, Min Success `>= 99.9%`, Max Cost `<= $4.80/hr`.

#### Episode 02: The Thundering Herd (`ep2-thundering-herd-cache`)
- **Symptom**: Flash sale starts (`5,000 req/s`). Product catalog crashes with 500 errors for 88% of shoppers.
- **Telemetry Findings**:
  - `cache` (Redis): Hot key `item:deal-of-century` (94% of traffic) expired at TTL `00:00:00`. Cache hit rate dropped from 99.4% to 14.2%.
  - `db` (PostgreSQL): 100% CPU saturation executing 4,710 duplicate queries/sec for the exact same product row.
- **Root Cause**: Cache Stampede (Thundering Herd) due to unsynchronized cache misses on a hot key.
- **Emergency Mitigation (1 min)**: Inject a static stale fallback in Redis and manually pre-warm the hot key.
- **Architectural Prevention**: Singleflight / Mutex request coalescing on cache miss + Probabilistic Early Refresh (XFetch algorithm).
- **SLA Targets**: Max P95 `<= 40 ms`, Min Success `>= 99.95%`, Max Cost `<= $3.50/hr`.

---

### Campaign 2: The Resilient Ledger (`campaign-resilience-consistency`)
- **Theme**: Distributed Transactions & Idempotency
- **Difficulty**: ADVANCED

#### Episode 01: The Double Charge Catastrophe (`ep1-double-charge-race`)
- **Symptom**: 18.4% of customers are charged multiple times during peak checkout (`3,000 req/s`), creating a `$428,000` ledger discrepancy.
- **Telemetry Findings**:
  - `client`: 1,200 req/s (40% of ingress) are retries carrying an identical `Client-Request-ID` arriving before the first payment finishes.
  - `payment_svc`: No atomic lock on the Idempotency Key; up to 4 parallel transactions execute per order.
- **Root Cause**: Non-Idempotent Concurrent Retries lacking distributed lock coordination.
- **Emergency Mitigation (2 min)**: Enable edge deduplication filter to reject duplicate client tokens within a 60-second window.
- **Architectural Prevention**: Transactional Idempotency Store + Distributed Lock (Redis `SETNX` / Redlock) tracking `IN_PROGRESS` and `COMPLETED` states with a Transactional Outbox.
- **SLA Targets**: Max P95 `<= 120 ms`, Min Success `100%`, Max Cost `<= $4.50/hr`.

---

## 5. Model Context Protocol (MCP) Server Specification

Queries Per Second ships with a stdio-based MCP server (`mcp-server/dist/index.js`) that syncs with the web workspace over WebSocket (`ws://localhost:3100`).

### MCP Client Configuration
```json
{
  "mcpServers": {
    "system-designer": {
      "command": "node",
      "args": ["/path/to/system-designer/mcp-server/dist/index.js"]
    }
  }
}
```

### Exposed MCP Resource
- `diagram://current` (`application/json`): Returns the active canvas `nodes` (id, label, type, category, capacity, quantity, position) and `edges` (id, source, target, trafficShare, fanout, isAsync).

### Exposed MCP Tools
- `add_node`: Add a module from the catalog to the canvas with custom label, capacity, quantity, and coordinates.
- `update_node`: Modify capacity, instance count (`quantity`), label, or type of an existing node.
- `remove_node`: Delete a node and its connected wires.
- `list_nodes`: List all nodes currently on the canvas.
- `move_node`: Reposition a node on the canvas.
- `connect_nodes`: Create a synchronous (`solid`) or asynchronous (`dashed`) wire between two nodes.
- `disconnect_nodes`: Remove an edge between nodes.
- `update_edge`: Configure custom labels, traffic share %, fanout multiplier, or sync/async line style.
- `list_edges`: List all connections in the topology.
- `get_diagram` / `import_diagram` / `clear_diagram` / `save_diagram` / `load_diagram` / `auto_layout`: Manage full topology state and automatic graph layout.
- `run_simulation`: Run the `FlowEngine` at a specified ingress QPS and return per-node utilization, P95/P99 latency, bottleneck warnings, and hourly cost.
- `get_available_components`: Query the 76 modules in `MODULE_CATALOG`.
- `list_challenges` / `start_challenge` / `get_challenge_info`: Inspect and launch SRE incident campaigns programmatically.