A Twitch extension that runs an autonomous, tick-based ZPG (zero-player game) inspired by Progress Quest, themed around a Dead by Daylight–style survival fiction. Viewers watch (and lightly direct) a survivor venturing into "the fog" while a streamer plays.
This document is the canonical context for the project. Read it before starting any non-trivial work. AI assistants (Claude Code, Cursor, etc.) should treat this as authoritative — if something here conflicts with assumptions in your training data, this document wins.
---
## 1. Product summary
- **What it is:** A Twitch Video Overlay extension. A small "lantern" sits on the streamer's broadcast; viewers see a survivor's mission unfold as a live log of encounters resolved every 60 seconds.
- **Why it exists:** Ambient stream entertainment. The streamer plays their game; the extension layers a parallel narrative driven by viewer participation without competing for attention.
- **Core loop:** Viewer's survivor enters a mission → server resolves an encounter every 60s using survivor stats + perks + RNG → log line streams to all viewers' overlays → mission ends in success/injury/sacrifice → progression updates persist.
- **Multiplayer:** "SWF" (Survive With Friends) groups of 2–4 survivors run shared missions with team perks and synchronized outcomes.
- **Frontend (overlay):** **Reconsider the original Angular choice** — the overlay UI is a single component with three states. Vanilla TypeScript + Lit (or hand-rolled) is likely a better fit. Smaller bundle = easier Twitch review. Decide before starting Stage 2.
- **Infra:** Docker Compose for local dev. Devcontainer for editor environment.
- **Shared types:** `@fog-explorer/api-interfaces` library, consumed by both apps. Use Zod schemas, not just TS types — runtime validation matters at the EBS boundary.
---
## 3. Twitch-specific constraints (read carefully — these shape architecture)
### Extension type
This is a **Video Overlay extension**, not a Panel extension. Configure the manifest accordingly. Streamers configure position; default to bottom-left.
### JWT and auth
- Twitch extension JWTs use **HS256** with the base64-decoded shared secret. Not RS256.
- Roles in the JWT: `viewer`, `broadcaster`, `external` (server-to-server). Treat them differently. Reject `broadcaster` for write actions unless explicitly streamer-only.
-`opaque_user_id` starts with `U` for logged-in viewers, `A` for anonymous. Anonymous viewers cannot have persistent survivors — they get a read-only view of the active mission.
### PubSub
- **1 message/sec per channel** for broadcaster messages. **Max 5KB payload.****No delivery guarantees.**
- Treat PubSub as a "hint to refresh" rather than authoritative state. Viewers who load mid-tick must be able to fetch state via REST.
- Batch all updates for a channel into a single PubSub message per tick.
- Frontend store must reconcile, not just append.
### HTTPS requirement
The EBS must serve HTTPS, even locally. Use Caddy or mkcert + Node TLS for dev.
### Review process
- Twitch reviews every version manually. **1–3 week cycles.** Plan for this; build for the review checklist from day one.
- CSP rules: no inline scripts, explicit allowlist for the EBS domain.
- No fingerprinting. GDPR-compliant handling of obfuscated user IDs.
- Working logged-out viewer experience is mandatory.
- Overlays must not obscure meaningful gameplay pixels. Streamer must have a kill switch.
---
## 4. Design direction
### Aesthetic
"Field journal in the fog." Muted desaturated palette, single warm accent (lantern amber `#E8A547`), cold red for danger (`#C03A3A`). Flat, printed, slightly weathered. No gradients, no drop shadows.
- Live log with progressive opacity (older lines fade).
- Single primary action button at the bottom when relevant; hidden when no action available.
- Backdrop dim/blur behind it to read against any stream content.
### Motion budget
Almost zero. Slow tick-drain animation, fade-in per log line, brief pulse on state changes, summon/unfold for the expanded card. Nothing else. Twitch viewers mute or hide animated panels.
### Accessibility
- Never encode state in colour alone. Vertical bar on survivor card changes shape (solid/dashed/crosshatched) per state. Log line colours are backed by glyphs.
- All custom monochrome glyphs (no emoji). Three glyphs minimum: difficulty pip, injury wound, perk-triggered.
### Group/SWF mode
Expanded card collapses the survivor section to a horizontal row of 4 portraits with state-coloured borders. The currently-resolving survivor highlights when their log line appears. Tap a portrait to expand detail. **Not yet mocked — design before Stage 3 group logic.**
### Streamer config screen
Separate from the viewer overlay. Live preview of the lantern in all four corner positions, one-click positioning, kill switch. Streamers who feel in control keep extensions installed.
### Empty/onboarding states
- **First-time viewer:** moody intro card, fog-shrouded silhouette, "The fog stirs. Awaiting a survivor." + Begin button. Only chance to explain what the extension is before they bounce.
- **Anonymous viewer:** desaturated lantern, no ticker, click to learn more. Don't hide the panel.
---
## 5. Build stages
### Stage 1 — Workspace & infrastructure
- Initialise Nx workspace with TypeScript, `@nx/angular` (or `@nx/js` if dropping Angular), `@nx/nest`, `@nx/node`.
- Configure `@nx/enforce-module-boundaries` with project tags (`scope:shared`, `scope:api`, `scope:overlay`). AI assistants love to reach across libraries with relative imports — enforce early.
-`.devcontainer/` directory with config (see Section 7).
### Stage 2 — Overlay frontend
- Decide framework first (Angular vs Lit vs vanilla). Smaller is better for review.
-`PanelShellComponent` mounting only after `window.Twitch.ext.onAuthorized` fires.
-`LiveLogComponent`, `SurvivorStatusComponent`, lantern + ticker components for the three states.
-`TwitchAuthService`: wraps `onAuthorized`, `onContext`, `onVisibilityChanged`. Stores JWT and parsed payload.
-`EbsApiService`: attaches `Authorization: Bearer <jwt>` to all calls. Uses `@fog-explorer/api-interfaces` types.
-`MissionStateStore`: signals or BehaviorSubject. Pulls initial state from REST, subscribes to PubSub for deltas.
- **Visibility lifecycle:** when overlay is hidden via `onVisibilityChanged`, stop PubSub processing and polling, but retain local state for instant re-expand.
- **Ambient event queue:** if events fire while collapsed, drop them and show current state on expand. Don't replay old drama.
### Stage 3 — Mission engine
-`TickEngineModule` with `TickService` using `@nestjs/schedule`. Global heartbeat per server, but **jitter `nextTickAt` per mission** to avoid thundering herd. Each mission has its own due time; worker picks up due ones.
- Distributed lock pattern: `SET key value NX PX <ttl>` with unique token, verify token before release. Or use Redlock. Naive `SETNX` without TTL = stuck tick on crash.
- **Encounter resolver — pure function** in `libs/mission-logic`. Signature `resolveEncounter(survivor, perks, difficulty, seed) → EncounterResult`. Use seeded PRNG (`seedrandom`), not `Math.random()`. Store seed per tick in `mission_logs` for replay/debug.
-`EncounterService` calls the resolver, updates state, emits log events.
- **Migrations from day one.** No "I'll add migrations later."
-`TwitchPubSubService`: signs messages with extension client ID + secret, publishes per-channel updates per tick.
- **Rate limit `/missions/state`** keyed off JWT `user_id`. A buggy panel could hammer it.
### Stage 5 — Content library & balance
-`@fog-explorer/encounter-library` with `encounters.json`. Records keyed by ID (`cleanse_hex`, `escape_hatch`, etc.) with: base success chance, difficulty tags, perk tags, **flavor text variants** (target 200+ per encounter type — this is the editorial product).
- **Version the encounter content.** In-flight missions use the version they started with; don't hot-swap.
-`PerkMath` helper: aggregates additive/multiplicative modifiers, separates survivor-level from team-level. Clamp `P{success}` to sane bounds.
- **Property-based tests** with `fast-check` on the resolver. Example tests pass while edge cases (modifier overflow, negative probabilities, empty perks) silently break.
- **Monte Carlo balance harness** in CI. Simulate 10k missions across perk loadouts. Snapshot test on success/injury/sacrifice distributions. Catches AI-generated balance numbers that *feel* reasonable but produce degenerate gameplay.
---
## 6. Cross-cutting concerns
### Observability
- Structured logging (pino) with correlation IDs: `missionId`, `tickIndex`, `channelId`, `opaqueUserId`. From day one.
- OpenTelemetry on the Nest side. Cheap to add upfront, painful later.
- Tag every log line emitted by the encounter resolver with the seed used. Debugging mission desyncs without this is misery.
### Data retention
-`mission_logs` will grow fast. Plan archival: partition by month, or TTL completed missions older than N days.
### Local dev without Twitch
- Add a `NODE_ENV=development` flag where the overlay mints a fake JWT and the API accepts it. 10× faster iteration than rigging the Twitch local test harness for every change. **Strictly dev-only — assert and fail loudly if seen in prod.**
### Monetisation seam
- Bits/transaction JWTs use a different flow. Even if not implementing now, stub the seam. Future Bits-driven mission events will be a small addition rather than a refactor.
---
## 7. Dev environment
### Host setup
- **Windows + WSL2 + devcontainer.** No dual-boot needed. Stack has no kernel/GPU dependencies; bare-metal Linux gives no measurable benefit and adds context-switch friction.
- **Code lives in WSL2 filesystem** (`~/code/fog-expedition`), not on `/mnt/c/`. The 9P boundary is 10–20× slower for filesystem ops; Nx with thousands of `node_modules` files will feel sluggish if mounted from Windows.
- VS Code with Dev Containers extension. Open the repo via Remote-WSL, then "Reopen in Container."
### Devcontainer config
-`.devcontainer/devcontainer.json` references the root `docker-compose.yml` plus a `docker-compose.dev.yml` overlay that adds the workspace service.
- Features: `docker-outside-of-docker` (lets the container run Docker commands against the host daemon — better than docker-in-docker), `github-cli`.
- VS Code extensions to preinstall: Nx Console, ESLint, Prettier, Jest Runner.
### Twitch dev rig integration
- The Twitch dev rig is an Electron app on the Windows side. It needs to reach the API.
- Bind Nest to `0.0.0.0`, not `127.0.0.1`. WSL2's localhost forwarding handles WSL2 → Windows; `forwardPorts` handles container → WSL2.
- HTTPS for EBS even locally. Add a `caddy` service to dev compose for TLS termination — three lines of config, avoids fiddling with Node TLS.
### File watching
- Nx file watchers use inotify. Inotify is unreliable on `/mnt/c/`. Inside WSL2 / devcontainer Linux filesystem, it works fine. This is another reason to keep code off the Windows drive.
---
## 8. AI-assisted build conventions
This project is being built with heavy AI assistance. A few conventions to keep things sane:
- **Lock the contracts before generating implementations.** Finish `@fog-explorer/api-interfaces` (Zod schemas, not just TS types) before generating controllers/services. AI is great at filling in implementations against tight contracts, terrible at maintaining consistency when types drift.
- **OpenAPI generation from Nest decorators.** Keeps the overlay client in sync automatically. Worth setting up Stage 1.
- **Property-based tests on pure functions.** Especially the encounter resolver. AI-generated example tests pass while edge cases break.
- **Monte Carlo balance harness as a snapshot test.** AI invents plausible-looking numbers that produce degenerate gameplay. Catch it in CI.
- **Module boundary enforcement.** `@nx/enforce-module-boundaries` with project tags. AI loves cross-library relative imports.
- **No hidden state in conversations.** Anything decided in chat that affects the codebase goes into a doc — this one, an ADR, or a code comment. Future-you and future-AI both need it.
---
## 9. Open decisions
Things deliberately not decided yet — flag them when you reach them:
- **ORM:** TypeORM vs Prisma vs Drizzle. Pick one before any DB code is written.
- **Group/SWF expanded UI:** designed conceptually, not mocked.
- **Streamer config screen:** designed conceptually, not mocked.
- **Custom glyph set:** placeholder Tabler icons used in mocks; commission three monochrome glyphs (difficulty pip, injury wound, perk-triggered) before submitting for review.
- **Hosted EBS domain:** required for Twitch review. Decide hosting (Fly.io, Railway, AWS, etc.) before Stage 4.
---
## 10. Out of scope (for v1)
- Bits-driven mission events (stub the seam, don't build).
- Multiple survivors per user (one survivor per user, who replaces them on death).
- Cross-channel persistence (survivors are scoped to the channel they were created on, for now).
- Mobile app (the Twitch mobile app renders extensions, but design-validate at desktop first).
- Streamer-customisable encounter content (single canonical content library for v1).
