#Math GDD documentation site

Status: proposed design, approved in chat on 2026-08-23

Repository: kiro/math-gdd

Canonical host: https://math-gdd.chowchowhome.duckdns.org

#Purpose

Build a small static documentation site that makes the current slot mathematics, GDDs, verification evidence and presentation flows easy to navigate. The repository's existing Markdown remains authoritative; the site is a rendered view over it, not a second source of truth.

The primary audience is the internal product, math, frontend and backend team. The page must answer three questions quickly:

1. Which game mathematics exist and what lifecycle state is each in?
2. Where are the GDD, Math Spec, evidence and changelog for a game?
3. What player-facing presentation flow does that game require?

#Scope

The game catalogue contains exactly four product games:

hold-and-win-reference is not a fifth game. It appears under Reusable mechanics, together with the generic expanding-wild and cascade presentation modules.

The first release includes the documentation site, build validation, immutable container image and automatic deployment from main. It does not edit game mathematics, change lifecycle states, publish a game, or expose any credential.

#Information architecture

The home page is a compact operational catalogue rather than a marketing landing page.

Math & GDD
├── Current games
│   ├── Classic Fruits 3×3
│   ├── Magic Vault 5×3
│   ├── Book of Odin v2
│   └── Vault Breakers: Super Score
├── Reusable mechanics
│   ├── Hold & Win
│   ├── Expanding Wild
│   └── Cascade / Tumble
└── Process
    ├── Slot math pipeline
    ├── GDD template
    ├── Math Spec template
    └── Presentation Flow template

Each game landing page contains:

• lifecycle badge and an explicit Draft/Final distinction;
• grid, evaluation model, target or measured RTP and primary mechanics;
• direct links to README, GDD, Math Spec, evidence manifest and changelog when present;
• a compact interactive presentation flow;
• open blockers copied from the authoritative game documents, never inferred from folder names;
• a visible link back to the source Markdown file.

Missing documents are shown as Not authored rather than hidden or represented by a broken link.

#Presentation flows

Flows are rendered as semantic HTML/CSS diagrams with keyboard-operable nodes. They are not screenshots and do not encode money or game outcomes independently of the backend contract.

#Classic Fruits 3×3

Ready → Spin → Reel stops
                  ├── no win → settle
                  ├── line win → line presentation → total
                  └── 7/8/9 SEVENS → jackpot presentation → total

The unique jackpot branch links to games/classic-fruits-3x3/gdd/sevens-jackpot-presentation.md.

#Magic Vault 5×3

Ready → Spin → paylines
                  ├── ordinary result → win/no-win settle
                  └── 6+ COIN → Hold & Win intro → respin loop → feature total → Ready

The full flow links to games/magic-vault-5x3/gdd/magic-vault-5x3-presentation-flow.md and the reusable Hold & Win module.

#Book of Odin v2

Ready → Spin → paylines
                  ├── BOOK trigger → Free Spins intro
                  │                   └── selected expanding symbol loop
                  └── 6+ bonus cells → Hold & Win loop
Free Spins may also enter Hold & Win, then return to the owning series.

The flow links to the Book of Odin GDD plus the reusable expanding-wild and Hold & Win modules. A dedicated Book of Odin presentation document may replace these links later without changing the site architecture.

#Vault Breakers: Super Score

Ready → Spin → snapshot
                  ├── regular win → remove → collapse/refill → next snapshot
                  ├── multiplier charges → accumulate for the sequence
                  ├── 4+ scatter-class → Free Spins
                  ├── Super Scatter → instant prize receipt
                  └── terminal snapshot → sequence total → Ready

The flow links to the game GDD and reusable cascade module. It must distinguish measured current behaviour from unresolved or historical DEV findings.

#Visual direction

The interface resembles a restrained math control room: dark graphite surfaces, fine grid lines, off-white text and one muted metal accent per game. Monochrome outline icons identify documents, evidence, lifecycle and flow states. Colour never carries status alone.

The signature element is the flow rail on each game page: the same visual grammar presents four different mechanics, while unique branches visibly change shape. Motion is limited to focus, hover and a short node-to-node trace; prefers-reduced-motion disables it.

The site supports desktop and mobile layouts, visible keyboard focus, semantic headings and screen-reader labels. It has no CDN or remotely loaded font/icon dependency.

#Source-of-truth boundary

• Existing files under games/, docs/ and templates/ remain authoritative.
• The site may hold thin MDX landing pages and presentation components, but must not copy Math Spec tables, evidence results or full GDD prose into a second maintained file.
• Catalogue metadata that is already present in a game README is read or linked from that README.
• A build-time validation list declares the four product games and the required document links. It is a navigation manifest, not a math registry.
• Backend config identity, Git SHA and SHA-256 remain owned by the game documents and backend.

#Build architecture

Rspress renders the repository Markdown and custom MDX/React landing pages into a static doc_build/ directory.

games/, docs/, templates/        site/theme/, site/components/
             \                    /
              └──── Rspress ─────┘
                       │
                  doc_build/
                       │
                  nginx image

The build uses pnpm with a committed lockfile. It requires no database, API or runtime Node process. The nginx container serves only generated static files on port 8080 and has a health endpoint or equivalent static-file probe.

Generated directories and dependency caches are ignored by Git. The committed repository does not contain a second generated copy of every Markdown page.

#CI pipeline

GitLab CI uses the existing VPS Docker runner pattern.

Before enabling the pipeline, verify that kiro/math-gdd has an eligible runner. A missing project assignment must fail the rollout checklist explicitly rather than leave every job pending. If the project uses the instance-scoped tools runner, every job carries its required tools tag; if it uses the project-scoped Kiro runner, the pipeline follows that runner's untagged convention.

#Check

Runs for merge requests and main:

1. frozen pnpm install;
2. typecheck/lint for custom site code;
3. Rspress production build;
4. internal-link validation;
5. assertion that all four game landing pages and their required flow links exist.

The build output is retained as a short-lived CI artifact for inspection.

#Image

Runs only on main after Check. It builds one nginx image and pushes both:

• $CI_REGISTRY_IMAGE:<CI_COMMIT_SHORT_SHA> — immutable deploy identity;
• $CI_REGISTRY_IMAGE:main — convenience pointer, never used as rollback evidence.

#Deploy

Runs only on main and deploys the immutable SHA tag using a compose file with no bind mounts. The job executes compose directly from the CI workspace, matching the kiro/game-client deployment pattern.

The container joins the external web network and carries:

labels:
  chow.host: math-gdd
  chow.port: "8080"
  chow.title: Slot Math & GDD
  chow.desc: Game mathematics, evidence and presentation flows
  chow.kind: service

No Caddyfile edit is allowed. chow-sites discovers the running container, generates the HTTPS vhost and dashboard tile within its normal 60-second cycle. Because math-gdd has no -dev or -stage suffix, the infrastructure applies the existing production basic_auth automatically.

The deploy gate verifies the container by its internal name over the web network before reporting success. It checks the home page and at least one game route from the deployed SHA.

#Deployment identity and rollback

The compose project name and container name are fixed and unique to this service; they must not use the generic directory-derived name deploy.

Deployment logs print the image SHA and container image identity. Rollback means setting the previous known-good SHA tag and recreating the same compose project. It does not rebuild an old commit or trust the mutable main tag.

Stopping the container removes its generated vhost and dashboard tile on the next registry cycle. No volume is attached, so the service owns no persistent runtime data.

#Security

• No credentials or files from pass/ enter the repository, image or build log.
• Authentication is enforced by the infrastructure-derived production-host policy.
• The container exposes port 8080 only to the web network; it publishes no host port.
• The image contains generated documentation, not .git, local evidence dumps or ignored art workspaces; .dockerignore enforces that boundary.
• Links to local absolute filesystem paths must not appear in the rendered navigation.
• A missing or malformed chow.host label fails deployment rather than falling back to an open host.

#Verification and acceptance

The first implementation is accepted when:

1. local development starts with one documented command;
2. the production build completes from a clean checkout with a frozen lockfile;
3. every visible internal link resolves in the built site;
4. the catalogue contains four games and does not count Hold & Win Reference as a game;
5. every game page has a readable flow on desktop and mobile;
6. keyboard users can traverse flow nodes and document links;
7. reduced-motion mode removes decorative flow animation;
8. the container serves the built home and game routes on port 8080;
9. CI publishes an immutable SHA image and deploys that exact image from main;
10. the VPS registry creates https://math-gdd.chowchowhome.duckdns.org with basic auth;
11. a documented previous SHA can be restored without rebuilding;
12. existing game math files and evidence are unchanged except for deliberate navigation links.

#Non-goals

• Editing or approving any game mathematics.
• Replacing Git history, Obsidian or backend canonical configs.
• External certification claims.
• A CMS, database, comments, authentication service or online Markdown editor.
• Publishing ignored raw art/video evidence.
• Hand-authoring a Caddy block or dashboard tile.
• Deploying stage/prod game runtimes.