fog/PROJECT_CONTEXT.md

Fog Expedition — Project Context

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.

---

2. Architecture overview

Twitch Video Overlay (panel)         NestJS API (EBS)
├── Lantern + ticker (minimised)     ├── /missions/* REST endpoints
├── Ambient event card               ├── Twitch JWT auth guard
└── Expanded survivor + log card     ├── Tick engine (60s heartbeat)
                                     ├── Encounter resolver (pure)
                                     ├── Group synergy service
                                     └── PubSub publisher

         │                                       │
         └────────── HTTPS + JWT ────────────────┘
                              │
                ┌─────────────┴─────────────┐
                │                           │
            Postgres                      Redis
            (durable state:           (active missions,
            users, survivors,         lobbies, tick locks,
            missions, logs)           rate limiting)
                              │
                Twitch Extension PubSub
                (server → viewer push)

Stack

• Monorepo: Nx workspace, pnpm package manager.
• Backend: NestJS (Node 20+, TypeScript). Modules: Auth, Missions, TickEngine, PubSub.
• 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.
• Datastores: Postgres (durable), Redis (ephemeral mission state, locks, lobbies).
• 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.

Typography

• Survivor names: condensed serif or slab (e.g. Cormorant). Grim-tarot feel.
• Live log: monospace (e.g. JetBrains Mono, IBM Plex Mono). Reinforces "transmission from the fog."
• UI chrome: clean sans.

Three overlay states

1. Minimised (default, ~95% of viewing time) — ~290×56px

• Circular lantern badge (~48px), state-coloured ring: amber=active, ochre=injured, red=sacrificed.
• Adjacent ticker showing the single latest log line in monospace, ellipsis truncation, no scrolling feed.
• Background: rgba(15, 18, 22, 0.88) — opacity ≥80% is non-negotiable for legibility over arbitrary stream content.

2. Ambient event (~290×92px, ~4s auto-dismiss)

• Triggers only on significant events: injury, sacrifice, mission complete, perk acquired. Not every tick.
• Slides up from the lantern with the event glyph and a one-line description.
• Use sparingly — overuse drives streamers to disable.

3. Expanded (lantern click) — ~320×440px

• Survivor card (portrait, name, state, perk slots).
• Mission strip (name, difficulty as 1–3 fog-glyphs, T+N tick counter, draining progress line).
• 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.
• Generate apps: overlay frontend, NestJS API.
• Generate @fog-explorer/api-interfaces lib with Zod schemas for Survivor, SurvivorState, Mission, MissionState, EncounterResult, Perk, PerkModifier.
• 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.
• Root docker-compose.yml: Postgres (named fog_expedition, healthcheck), Redis, optional API service.
• .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.
• GroupSynergyService aggregates each participant's survivor perks for SWF missions, applies combined modifiers to all relevant rolls.
• MissionStore repository abstracting Redis. Keys: active_mission:{id}, mission_lobby:{id}.

Stage 4 — EBS persistence

• MissionsController: POST /missions/start, GET /missions/state, POST /missions/choose-perk. DTOs from @fog-explorer/api-interfaces.
• TwitchAuthGuard: HS256 JWT verification, attach opaqueUserId and channelId to request. Reject expired or wrong-role tokens.
• Postgres schema (TypeORM or Prisma — pick one and stick to it):
  • users (id, twitch_opaque_user_id, created_at)
  • survivors (id, user_id FK, stats JSONB, perk_slots JSONB, state, created_at)
  • missions (id, group_id nullable, difficulty, status, started_at, ended_at)
  • mission_logs (id, mission_id FK, tick_index, encounter_key, rendered_text, seed, modifiers_applied JSONB)
• 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).
• TS wrapper: getEncounterById, getRandomEncounterByTier, pickFlavor(encounter, context).
• 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.
• forwardPorts: 3000 (API), 4200 (overlay dev server), 5432 (Postgres), 6379 (Redis).
• postCreateCommand: pnpm install.
• 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:

• Overlay framework: Decided — Angular. See ADR-0008.
• 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).