# samithathiyagarajan/ticket-stampede architecture

> Architecture diagram of the GitHub repository samithathiyagarajan/ticket-stampede, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/samithathiyagarajan/ticket-stampede
- Repository: https://github.com/samithathiyagarajan/ticket-stampede

## Overview

Ticket Stampede is a ticket-selling backend designed to preserve sale invariants under concurrent purchase requests and database failures. The main workflow resets a sale, submits purchases through the service, and verifies responses against a final status snapshot. The README documents the multi-seller/nginx deployment, load generation, failure experiments, and offline evidence viewer. Source excerpts show the seller’s transaction and status behavior plus buyer request and verification flow; some deployment and diagnostic wiring is based on README documentation rather than sampled implementation.

Main entry points: [`seller/app.py`](https://github.com/samithathiyagarajan/ticket-stampede/blob/master/seller/app.py) (Seller API), [`buyer/buyer.py`](https://github.com/samithathiyagarajan/ticket-stampede/blob/master/buyer/buyer.py) (Load Generator), [`diag/analyze_commit_drop.py`](https://github.com/samithathiyagarajan/ticket-stampede/blob/master/diag/analyze_commit_drop.py) (Commit Drop Analysis), [`scripts/replay_check.py`](https://github.com/samithathiyagarajan/ticket-stampede/blob/master/scripts/replay_check.py) (Recovery Replay Check)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_purchase["Ticket Service"]
  node_seller_api["Seller API<br/>[app.py]"]
  node_safe_schema["Safe Constraints<br/>[schema_safe.sql]"]
  node_naive_schema["Naive Schema<br/>[schema_naive.sql]"]
  node_nginx["Load Balancer<br/>[nginx.conf]"]
  node_postgres[("PostgreSQL")]
end

subgraph group_load["Load and Verify"]
  node_buyer["Load Generator<br/>[buyer.py]"]
  node_verifier["Invariant Verifier<br/>[buyer.py]"]
end

subgraph group_resilience["Failure Diagnostics"]
  node_pg_sampler["DB Sampler<br/>[pgsample.py]"]
  node_fault_injector["Fault Injector<br/>[inject_db_fault.sh]"]
  node_commit_proxy["Commit Drop Proxy"]
  node_commit_analysis["Commit Drop Analysis"]
  node_reset_replay["Recovery Replay Check<br/>[replay_check.py]"]
  node_reset_analysis["Network Reset Analysis<br/>[analyze_resets.py]"]
end

subgraph group_evidence["Evidence Viewer"]
  node_viewer["Offline Evidence Viewer<br/>[index.html]"]
end

node_buyer_user(("Buyer / Operator"))

node_buyer_user -->|"starts run"| node_buyer
node_buyer -->|"sends purchases"| node_nginx
node_buyer -->|"calls reset"| node_seller_api
node_nginx -->|"routes requests"| node_seller_api
node_seller_api -->|"reads and writes"| node_postgres
node_seller_api -->|"loads schema"| node_safe_schema
node_seller_api -->|"loads schema"| node_naive_schema
node_buyer -->|"reads status"| node_seller_api
node_buyer -->|"passes raw results"| node_verifier
node_verifier -->|"checks final state"| node_postgres
node_pg_sampler -->|"samples sessions"| node_postgres
node_fault_injector -->|"injects faults"| node_postgres
node_seller_api -.->|"connects through"| node_commit_proxy
node_commit_proxy -.->|"forwards traffic"| node_postgres
node_commit_analysis -.->|"audits rows"| node_postgres
node_commit_analysis -.->|"replays purchases"| node_seller_api
node_reset_replay -->|"replays requests"| node_seller_api
node_reset_replay -->|"audits constraints"| node_postgres
node_reset_analysis -.->|"matches reset events"| node_buyer
node_buyer_user -->|"views evidence"| node_viewer

click node_buyer "https://github.com/samithathiyagarajan/ticket-stampede/blob/master/buyer/buyer.py"
click node_verifier "https://github.com/samithathiyagarajan/ticket-stampede/blob/master/buyer/buyer.py"
click node_seller_api "https://github.com/samithathiyagarajan/ticket-stampede/blob/master/seller/app.py"
click node_safe_schema "https://github.com/samithathiyagarajan/ticket-stampede/blob/master/seller/schema_safe.sql"
click node_naive_schema "https://github.com/samithathiyagarajan/ticket-stampede/blob/master/seller/schema_naive.sql"
click node_nginx "https://github.com/samithathiyagarajan/ticket-stampede/blob/master/lb/nginx.conf"
click node_pg_sampler "https://github.com/samithathiyagarajan/ticket-stampede/blob/master/buyer/pgsample.py"
click node_fault_injector "https://github.com/samithathiyagarajan/ticket-stampede/blob/master/scripts/inject_db_fault.sh"
click node_commit_proxy "https://github.com/samithathiyagarajan/ticket-stampede/blob/master/diag/commit_drop_proxy.py"
click node_commit_analysis "https://github.com/samithathiyagarajan/ticket-stampede/blob/master/diag/analyze_commit_drop.py"
click node_reset_replay "https://github.com/samithathiyagarajan/ticket-stampede/blob/master/scripts/replay_check.py"
click node_reset_analysis "https://github.com/samithathiyagarajan/ticket-stampede/blob/master/diag/analyze_resets.py"
click node_viewer "https://github.com/samithathiyagarajan/ticket-stampede/blob/master/viewer/index.html"

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_seller_api,node_safe_schema,node_naive_schema,node_nginx,node_postgres toneBlue
class node_buyer,node_verifier toneAmber
class node_pg_sampler,node_fault_injector,node_commit_proxy,node_commit_analysis,node_reset_replay,node_reset_analysis toneMint
class node_viewer toneRose
class node_buyer_user toneIndigo
```

## Components

### Ticket Service

- [Seller API](https://github.com/samithathiyagarajan/ticket-stampede/blob/master/seller/app.py): `seller/app.py`
- [Safe Constraints](https://github.com/samithathiyagarajan/ticket-stampede/blob/master/seller/schema_safe.sql): `seller/schema_safe.sql`
- [Naive Schema](https://github.com/samithathiyagarajan/ticket-stampede/blob/master/seller/schema_naive.sql): `seller/schema_naive.sql`
- [Load Balancer](https://github.com/samithathiyagarajan/ticket-stampede/blob/master/lb/nginx.conf): `lb/nginx.conf`
- **PostgreSQL**

### Load and Verify

- [Load Generator](https://github.com/samithathiyagarajan/ticket-stampede/blob/master/buyer/buyer.py): `buyer/buyer.py`
- [Invariant Verifier](https://github.com/samithathiyagarajan/ticket-stampede/blob/master/buyer/buyer.py): `buyer/buyer.py`

### Failure Diagnostics

- [DB Sampler](https://github.com/samithathiyagarajan/ticket-stampede/blob/master/buyer/pgsample.py): `buyer/pgsample.py`
- [Fault Injector](https://github.com/samithathiyagarajan/ticket-stampede/blob/master/scripts/inject_db_fault.sh): `scripts/inject_db_fault.sh`
- [Commit Drop Proxy](https://github.com/samithathiyagarajan/ticket-stampede/blob/master/diag/commit_drop_proxy.py): `diag/commit_drop_proxy.py`
- [Commit Drop Analysis](https://github.com/samithathiyagarajan/ticket-stampede/blob/master/diag/analyze_commit_drop.py): `diag/analyze_commit_drop.py`
- [Recovery Replay Check](https://github.com/samithathiyagarajan/ticket-stampede/blob/master/scripts/replay_check.py): `scripts/replay_check.py`
- [Network Reset Analysis](https://github.com/samithathiyagarajan/ticket-stampede/blob/master/diag/analyze_resets.py): `diag/analyze_resets.py`

### Evidence Viewer

- [Offline Evidence Viewer](https://github.com/samithathiyagarajan/ticket-stampede/blob/master/viewer/index.html): `viewer/index.html`

### Other components

- **Buyer / Operator**

## Connections

- Buyer / Operator → Load Generator: starts run
- Load Generator → Load Balancer: sends purchases
- Load Generator → Seller API: calls reset
- Load Balancer → Seller API: routes requests
- Seller API → PostgreSQL: reads and writes
- Seller API → Safe Constraints: loads schema
- Seller API → Naive Schema: loads schema
- Load Generator → Seller API: reads status
- Load Generator → Invariant Verifier: passes raw results
- Invariant Verifier → PostgreSQL: checks final state
- DB Sampler → PostgreSQL: samples sessions
- Fault Injector → PostgreSQL: injects faults
- Seller API → Commit Drop Proxy: connects through
- Commit Drop Proxy → PostgreSQL: forwards traffic
- Commit Drop Analysis → PostgreSQL: audits rows
- Commit Drop Analysis → Seller API: replays purchases
- Recovery Replay Check → Seller API: replays requests
- Recovery Replay Check → PostgreSQL: audits constraints
- Network Reset Analysis → Load Generator: matches reset events
- Buyer / Operator → Offline Evidence Viewer: views evidence