# Game design document

> The internal design document: every system, formula, and open question behind the game.

This is the internal design document behind Quorum, an incremental systems game in the spirit of
Upload Labs and Factorio, built on real engineering behavior. The game is the source of truth for
every number, and these pages describe what it does.

## The game in one paragraph

You are the first engineer of a startup. Users send requests, and you wire Components on a board,
pick the runtime and framework that each server runs, and watch requests flow through your design
as particles. Served requests earn Cash. Sampled traffic earns Insight, which buys research. Each
fix moves the bottleneck somewhere else, and funding rounds bring new kinds of requests that break
your design in new ways. At the end of a company you Exit, earn Legacy, and found a new company with
different rules.

Every number comes from a real behavior. PHP-FPM workers run out of memory, a Node.js event loop
stalls on bcrypt, a JVM is slow until it warms up, and an average latency hides the p99.

## Table of Contents

| # | Document | Answers |
| --- | --- | --- |
| 1 | [Vision and pillars](https://wiki.playquorum.dev/design/01-vision.md) | What the game is, who it is for, and the rules every design decision follows. |
| 2 | [Influences and research](https://wiki.playquorum.dev/design/02-influences.md) | Why players love Upload Labs, Factorio, and Opus Magnum, and why some players quit. |
| 3 | [Game loops](https://wiki.playquorum.dev/design/03-game-loops.md) | The six nested loops, from a two-second glance to a hundred-hour mastery goal. |
| 4 | [Simulation](https://wiki.playquorum.dev/design/04-simulation.md) | How requests, capacity, queues, latency, errors, and users are calculated. |
| 5 | [Components](https://wiki.playquorum.dev/design/05-components.md) | Every placeable Component, its real product, its stats, and its options. |
| 6 | [Runtimes and frameworks](https://wiki.playquorum.dev/design/06-runtimes.md) | Languages, runtime variants, and frameworks as tradeoffs, not tiers. |
| 7 | [Data tier](https://wiki.playquorum.dev/design/07-data-tier.md) | Databases, caches, replicas, quorums, consistency, and storage. |
| 8 | [Team and velocity](https://wiki.playquorum.dev/design/08-team-and-velocity.md) | Engineers, Dev Hours, features, tech debt, services, and Conway's law. |
| 9 | [Economy](https://wiki.playquorum.dev/design/09-economy.md) | Currencies, sources and sinks, the cloud bill, pricing models, and funding. |
| 10 | [Progression](https://wiki.playquorum.dev/design/10-progression.md) | Eras, the research tree, product features, and pacing targets. |
| 11 | [Incidents and reliability](https://wiki.playquorum.dev/design/11-incidents.md) | The incident catalog, the incident loop, SLOs, and error budgets. |
| 12 | [Observability and Insight](https://wiki.playquorum.dev/design/12-observability.md) | Fog of war for systems: what the player can see and how they earn the right to see more. |
| 13 | [Exit and Legacy](https://wiki.playquorum.dev/design/13-prestige.md) | The prestige layer: Exits, Legacy, Ventures, and Mutators. |
| 14 | [Sandbox, Challenges, and achievements](https://wiki.playquorum.dev/design/14-challenges.md) | Guided and free Sandboxes, fixed puzzles with histograms, daily drills, and achievements. |
| 15 | [Interface and game feel](https://wiki.playquorum.dev/design/15-ui-ux.md) | The board, Node cards, feedback, bulk actions, and accessibility. |
| 16 | [Balancing](https://wiki.playquorum.dev/design/16-balancing.md) | Every formula, every tunable constant, and the pacing model. |
| 17 | [Scope and roadmap](https://wiki.playquorum.dev/design/17-scope-and-roadmap.md) | What the game contains, the milestones, and open questions. |
| 18 | [Mail](https://wiki.playquorum.dev/design/18-mail.md) | Mail: colour-coded senders, threads, teammates, CVEs, and spam as the game's main channel. |
| — | [Measurements](https://wiki.playquorum.dev/design/measurements.md) | Balance snapshots taken at a named simulation version. |

## Reference documents

| Document | Use it for |
| --- | --- |
| [CONTEXT.md](https://github.com/elianiva/quorum/blob/main/CONTEXT.md) | The game vocabulary. Code, UI copy, and these documents use these words. |
| [Engineering glossary](https://wiki.playquorum.dev/glossary.md) | Real engineering terms that the game teaches, each linked to its mechanic. |
| [Reality check](https://wiki.playquorum.dev/design/reality-check.md) | Each real-world claim, the game rule built on it, the simplification, and its source. |
| [Decision records](https://github.com/elianiva/quorum/tree/main/docs/adr) | The reasons behind load-bearing decisions. |

## Conventions in these documents

- **Bold Capitalized** words, such as **Node**, **Era**, and **Insight**, are game terms defined in
  [CONTEXT.md](https://github.com/elianiva/quorum/blob/main/CONTEXT.md).
- Engineering terms, such as [event loop](https://wiki.playquorum.dev/glossary/event-loop.md), link to the
  [engineering glossary](https://wiki.playquorum.dev/glossary.md).
- Every number is a balance target unless the text says otherwise. The source of truth for numbers
  in code is `packages/simulation/src/catalog.ts`. When this document and the catalog disagree,
  [Balancing](https://wiki.playquorum.dev/design/16-balancing.md) records which one wins.
- "Real" marks a behavior taken from real systems. "Stylized" marks a behavior that the game
  simplifies or exaggerates for play. [Reality check](https://wiki.playquorum.dev/design/reality-check.md) lists both.

Source: https://wiki.playquorum.dev/design