🛠 Fate's Edge / dev

Systems Architecture

Fate's Edge is a system of systems: a tabletop ruleset, an LLM-driven Game Master built on top of it, a real-time transport fabric connecting a dozen client surfaces to that GM, and an optional voice pipeline layered on top of all of it.

The full write-up lives in fates-edge-docs/ARCHITECTURE.md (companion to fates-edge-ai-gm-bot's DESIGN.md) — this page is the map, not the territory.

┌─────────────────────────────────────────────────────────────────────┐
│  Layer 4 — Voice: Chatterbox (TTS) → voice-adapter → RVC (optional)  │
├─────────────────────────────────────────────────────────────────────┤
│  Layer 3 — Clients: web · desktop · terminal · Discord · Roll20 ·    │
│            Foundry · Python CLI/GUI                                  │
├─────────────────────────────────────────────────────────────────────┤
│  Layer 2 — Transport: socket server (Socket.IO + plain WS, rooms)    │
├─────────────────────────────────────────────────────────────────────┤
│  Layer 1 — AI GM Bot: driver-agnostic LLM orchestration, tag DSL,    │
│            adventure state machine                                   │
├─────────────────────────────────────────────────────────────────────┤
│  Layer 0 — Rules Engine: d10 pool, Outcome Matrix, Position, SB,     │
│            Boons, Obligation, Timers                                 │
└─────────────────────────────────────────────────────────────────────┘

Layer 0 is a formal system the game defines and the software encodes. Layer 1 is the only layer that talks to an LLM at all — everything from Layer 2 down has no idea an AI is involved. A human GM running the same socket server, web client, and voice pipeline gets identical infrastructure. That separation is deliberate, and it's why every layer above Layer 0 is genuinely optional.

Layer 0 — Rules Engine

A deterministic d10 pool system: Outcome Matrix, Position, Stress/Boons, Obligation, and Timers. No hidden GM logic, no opaque heuristics — anything the AI GM decides, a human GM (or a script) could decide the same way from the same visible state.

Layer 1 — AI GM Bot

Driver-agnostic LLM orchestration over an adventure state machine, communicating exclusively through the tag-based GM protocol below. Swapping LLM providers, or removing the AI entirely, doesn't touch layers 2–4.

Tag DSL / GM Protocol

Every GM action — scene transitions, skill check outcomes, state changes — is expressed as a small, typed, test-covered directive rather than free-form text. This is the highest-leverage place to contribute if you want to extend what the GM (human or AI) can express. See Ways to Contribute.

Layer 2 — Transport

A socket server (Socket.IO plus plain WebSocket, room-based) that gives every client surface — web, desktop, terminal, Discord, Roll20, Foundry, Python — identical real-time event access to a session, regardless of which GM (human or AI) is running it.

Layer 3 — Clients

Web client, desktop client, terminal (ANSI) client, and bridges into Discord, Roll20, Foundry, and a Python CLI/GUI. Each one only needs to speak the room protocol from Layer 2.

Layer 4 — Voice Stack

Chatterbox (TTS) → voice-adapter → RVC (voice cloning), fully optional and toggleable independently of everything else.

Repositories