# yasher3413/aftershock architecture

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

- Interactive diagram: https://gitdiagram.com/yasher3413/aftershock
- Repository: https://github.com/yasher3413/aftershock

## Overview

Aftershock turns NHL play-by-play into live and replayed estimates of how goals change playoff odds, then presents those changes as a map, seismograph, player/team views, and shareable recaps. Its central workflow is NHL feed → normalized game data → live/replay engine and season simulation → persisted tremors and published state → API → web experience. The README documents the major capabilities and system boundaries; some implementation paths below are directory-level because their source was not sampled.

Main entry points: [`services/aftershock/db/models.py`](https://github.com/yasher3413/aftershock/blob/main/services/aftershock/db/models.py) (Postgres), [`services/aftershock/nhl/parse.py`](https://github.com/yasher3413/aftershock/blob/main/services/aftershock/nhl/parse.py) (Game parser), [`services/aftershock/live/engine.py`](https://github.com/yasher3413/aftershock/blob/main/services/aftershock/live/engine.py) (Season engine), [`web/src/routes.tsx`](https://github.com/yasher3413/aftershock/blob/main/web/src/routes.tsx) (Web application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_feed["Feed and storage"]
  node_fetch["Feed client<br/>[client.py]"]
  node_parse["Game parser<br/>[parse.py]"]
  node_ingest["Historical ingest<br/>[load.py]"]
  node_database[("Postgres<br/>[models.py]")]
end

subgraph group_models["Models and simulation"]
  node_xg["Expected goals<br/>[xg.py]"]
  node_strength["Team strength<br/>[strength.py]"]
  node_winprob["Win probability<br/>[wp.py]"]
  node_siminputs["Simulation inputs<br/>[inputs.py]"]
  node_backend["Rust simulator adapter<br/>[backend.py]"]
  node_core["Season simulator<br/>[mod.rs]"]
  node_standings["Standings and playoffs<br/>[standings.rs]"]
  node_wasm["Browser simulator<br/>[lib.rs]"]
end

subgraph group_runtime["Live runtime"]
  node_engine["Season engine<br/>[engine.py]"]
  node_worker["Live and replay worker<br/>[worker.py]"]
  node_tremors["Tremor scoring<br/>[compute.py]"]
  node_persist["Effect persistence<br/>[persist.py]"]
  node_publish["Live publishing<br/>[publish.py]"]
  node_recap["Nightly recap<br/>[generate.py]"]
end

subgraph group_delivery["API and delivery"]
  node_api["REST and WebSocket API<br/>[app.py]"]
  node_redis["Redis pub/sub"]
end

subgraph group_experience["Web experience"]
  node_web["Web application<br/>[routes.tsx]"]
  node_map["Live shockwave map<br/>[controller.ts]"]
  node_whatif["What-If Lab<br/>[useSimulator.ts]"]
end

node_nhl(("NHL feed"))
node_viewer(("Hockey viewer"))

node_nhl -->|"serves feed"| node_fetch
node_fetch -->|"provides JSON"| node_parse
node_parse -.->|"normalizes data"| node_ingest
node_ingest -.->|"loads games"| node_database
node_parse -->|"provides plays"| node_xg
node_parse -->|"provides plays"| node_winprob
node_strength -->|"supplies matchup"| node_winprob
node_database -->|"loads season"| node_siminputs
node_strength -->|"fills probabilities"| node_siminputs
node_siminputs -->|"provides inputs"| node_backend
node_backend -.->|"invokes simulator"| node_core
node_core -->|"computes standings"| node_standings
node_worker -->|"drives snapshots"| node_engine
node_engine -->|"evaluates game state"| node_winprob
node_engine -->|"runs season simulations"| node_backend
node_engine -->|"computes tremors"| node_tremors
node_worker -.->|"persists effects"| node_persist
node_worker -.->|"publishes state"| node_publish
node_persist -.->|"writes results"| node_database
node_publish -->|"publishes messages"| node_redis
node_redis -->|"feeds updates"| node_api
node_database -->|"serves queries"| node_api
node_api -->|"serves REST and socket"| node_web
node_viewer -->|"views results"| node_web
node_web -.->|"renders live map"| node_map
node_web -.->|"opens scenarios"| node_whatif
node_whatif -->|"runs browser simulation"| node_wasm
node_database -.->|"supplies nightly data"| node_recap

click node_fetch "https://github.com/yasher3413/aftershock/blob/main/services/aftershock/nhl/client.py"
click node_parse "https://github.com/yasher3413/aftershock/blob/main/services/aftershock/nhl/parse.py"
click node_ingest "https://github.com/yasher3413/aftershock/blob/main/services/aftershock/ingest/load.py"
click node_database "https://github.com/yasher3413/aftershock/blob/main/services/aftershock/db/models.py"
click node_xg "https://github.com/yasher3413/aftershock/blob/main/services/aftershock/ml/xg.py"
click node_strength "https://github.com/yasher3413/aftershock/blob/main/services/aftershock/ml/strength.py"
click node_winprob "https://github.com/yasher3413/aftershock/blob/main/services/aftershock/ml/wp.py"
click node_siminputs "https://github.com/yasher3413/aftershock/blob/main/services/aftershock/sim/inputs.py"
click node_backend "https://github.com/yasher3413/aftershock/blob/main/services/aftershock/sim/backend.py"
click node_core "https://github.com/yasher3413/aftershock/blob/main/crates/aftershock-core/src/sim/mod.rs"
click node_standings "https://github.com/yasher3413/aftershock/blob/main/crates/aftershock-core/src/standings.rs"
click node_engine "https://github.com/yasher3413/aftershock/blob/main/services/aftershock/live/engine.py"
click node_worker "https://github.com/yasher3413/aftershock/blob/main/services/aftershock/live/worker.py"
click node_tremors "https://github.com/yasher3413/aftershock/blob/main/services/aftershock/tremors/compute.py"
click node_persist "https://github.com/yasher3413/aftershock/blob/main/services/aftershock/live/persist.py"
click node_publish "https://github.com/yasher3413/aftershock/blob/main/services/aftershock/live/publish.py"
click node_recap "https://github.com/yasher3413/aftershock/blob/main/services/aftershock/recap/generate.py"
click node_api "https://github.com/yasher3413/aftershock/blob/main/services/aftershock/api/app.py"
click node_web "https://github.com/yasher3413/aftershock/blob/main/web/src/routes.tsx"
click node_map "https://github.com/yasher3413/aftershock/blob/main/web/src/map/controller.ts"
click node_whatif "https://github.com/yasher3413/aftershock/blob/main/web/src/whatif/useSimulator.ts"
click node_wasm "https://github.com/yasher3413/aftershock/blob/main/crates/aftershock-wasm/src/lib.rs"

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_fetch,node_parse,node_ingest,node_database,node_viewer toneBlue
class node_xg,node_strength,node_winprob,node_siminputs,node_backend,node_core,node_standings,node_wasm toneAmber
class node_engine,node_worker,node_tremors,node_persist,node_publish,node_recap toneMint
class node_api,node_redis toneRose
class node_web,node_map,node_whatif,node_nhl toneIndigo
```

## Components

### Feed and storage

- [Feed client](https://github.com/yasher3413/aftershock/blob/main/services/aftershock/nhl/client.py): `services/aftershock/nhl/client.py`
- [Game parser](https://github.com/yasher3413/aftershock/blob/main/services/aftershock/nhl/parse.py): `services/aftershock/nhl/parse.py`
- [Historical ingest](https://github.com/yasher3413/aftershock/blob/main/services/aftershock/ingest/load.py): `services/aftershock/ingest/load.py`
- [Postgres](https://github.com/yasher3413/aftershock/blob/main/services/aftershock/db/models.py): `services/aftershock/db/models.py`

### Models and simulation

- [Expected goals](https://github.com/yasher3413/aftershock/blob/main/services/aftershock/ml/xg.py): `services/aftershock/ml/xg.py`
- [Team strength](https://github.com/yasher3413/aftershock/blob/main/services/aftershock/ml/strength.py): `services/aftershock/ml/strength.py`
- [Win probability](https://github.com/yasher3413/aftershock/blob/main/services/aftershock/ml/wp.py): `services/aftershock/ml/wp.py`
- [Simulation inputs](https://github.com/yasher3413/aftershock/blob/main/services/aftershock/sim/inputs.py): `services/aftershock/sim/inputs.py`
- [Rust simulator adapter](https://github.com/yasher3413/aftershock/blob/main/services/aftershock/sim/backend.py): `services/aftershock/sim/backend.py`
- [Season simulator](https://github.com/yasher3413/aftershock/blob/main/crates/aftershock-core/src/sim/mod.rs): `crates/aftershock-core/src/sim/mod.rs`
- [Standings and playoffs](https://github.com/yasher3413/aftershock/blob/main/crates/aftershock-core/src/standings.rs): `crates/aftershock-core/src/standings.rs`
- [Browser simulator](https://github.com/yasher3413/aftershock/blob/main/crates/aftershock-wasm/src/lib.rs): `crates/aftershock-wasm/src/lib.rs`

### Live runtime

- [Season engine](https://github.com/yasher3413/aftershock/blob/main/services/aftershock/live/engine.py): `services/aftershock/live/engine.py`
- [Live and replay worker](https://github.com/yasher3413/aftershock/blob/main/services/aftershock/live/worker.py): `services/aftershock/live/worker.py`
- [Tremor scoring](https://github.com/yasher3413/aftershock/blob/main/services/aftershock/tremors/compute.py): `services/aftershock/tremors/compute.py`
- [Effect persistence](https://github.com/yasher3413/aftershock/blob/main/services/aftershock/live/persist.py): `services/aftershock/live/persist.py`
- [Live publishing](https://github.com/yasher3413/aftershock/blob/main/services/aftershock/live/publish.py): `services/aftershock/live/publish.py`
- [Nightly recap](https://github.com/yasher3413/aftershock/blob/main/services/aftershock/recap/generate.py): `services/aftershock/recap/generate.py`

### API and delivery

- [REST and WebSocket API](https://github.com/yasher3413/aftershock/blob/main/services/aftershock/api/app.py): `services/aftershock/api/app.py`
- **Redis pub/sub**

### Web experience

- [Web application](https://github.com/yasher3413/aftershock/blob/main/web/src/routes.tsx): `web/src/routes.tsx`
- [Live shockwave map](https://github.com/yasher3413/aftershock/blob/main/web/src/map/controller.ts): `web/src/map/controller.ts`
- [What-If Lab](https://github.com/yasher3413/aftershock/blob/main/web/src/whatif/useSimulator.ts): `web/src/whatif/useSimulator.ts`

### Other components

- **NHL feed**
- **Hockey viewer**

## Connections

- NHL feed → Feed client: serves feed (evidence: `README.md`)
- Feed client → Game parser: provides JSON (evidence: `services/aftershock/nhl/client.py`)
- Game parser → Historical ingest: normalizes data
- Historical ingest → Postgres: loads games
- Game parser → Expected goals: provides plays (evidence: `services/aftershock/ml/xg.py`)
- Game parser → Win probability: provides plays (evidence: `services/aftershock/ml/wp.py`)
- Team strength → Win probability: supplies matchup (evidence: `services/aftershock/ml/wp.py`)
- Postgres → Simulation inputs: loads season (evidence: `services/aftershock/sim/inputs.py`)
- Team strength → Simulation inputs: fills probabilities (evidence: `services/aftershock/sim/inputs.py`)
- Simulation inputs → Rust simulator adapter: provides inputs (evidence: `services/aftershock/sim/backend.py`)
- Rust simulator adapter → Season simulator: invokes simulator
- Season simulator → Standings and playoffs: computes standings (evidence: `crates/aftershock-core/src/sim/mod.rs`)
- Live and replay worker → Season engine: drives snapshots (evidence: `README.md`)
- Season engine → Win probability: evaluates game state (evidence: `services/aftershock/live/engine.py`)
- Season engine → Rust simulator adapter: runs season simulations (evidence: `services/aftershock/live/engine.py`)
- Season engine → Tremor scoring: computes tremors (evidence: `services/aftershock/live/engine.py`)
- Live and replay worker → Effect persistence: persists effects
- Live and replay worker → Live publishing: publishes state
- Effect persistence → Postgres: writes results
- Live publishing → Redis pub/sub: publishes messages (evidence: `README.md`)
- Redis pub/sub → REST and WebSocket API: feeds updates (evidence: `README.md`)
- Postgres → REST and WebSocket API: serves queries (evidence: `README.md`)
- REST and WebSocket API → Web application: serves REST and socket (evidence: `README.md`)
- Hockey viewer → Web application: views results (evidence: `README.md`)
- Web application → Live shockwave map: renders live map
- Web application → What-If Lab: opens scenarios
- What-If Lab → Browser simulator: runs browser simulation (evidence: `README.md`)
- Postgres → Nightly recap: supplies nightly data
