Dispute Flow — internal documentation

Internal documentation for Dispute Flow — the chargeback-dispute platform. Private: this site is not written for search engines and is meant to sit behind access control on its deployment.

Roadmap

The milestone map the Linear board mirrors — M0 through M7, what each delivers, what is deferred, and the full requirement-coverage index back to the FRD, FSD and DELTA.

Architecture

The production shape: a synchronous NestJS monolith on Postgres, and the email processing engine that turns an inbound dispute mailbox into cases.

How the site works

Dispute Flow is a single product, so the sidebar has no per-module split — its top-level entries are the sections themselves. Everything published here lives in the repository’s docs/ and overview/ folders; the site shows a curated subset, not the whole corpus.

At build time apps/docs/scripts/sync-product-docs.mjs copies in every markdown file whose name carries the .docs.md marker (and any image it embeds). The files never move — the repo stays the single source, and the marker is stripped from the URL. The repository holds far more than the site shows: research notes, superseded decisions and per-issue build notes stay in the repo as history.

Publish a document

Change the document’s shape. Add frontmatter and delete the # H1 — Starlight renders the frontmatter title as the heading, so keeping the H1 would print it twice:
```
---
title: "System architecture"
description: "The production shape of the platform."
---
# System architecture — the production shape
```

Rename the file — the marker is the whole opt-in:

architecture.md       →  internal
architecture.docs.md  →  published

Add one sidebar entry in apps/docs/astro.config.mjs (no .docs, no .md in the slug):
```
{ label: "System architecture", slug: "overview/architecture" },
```

Verify with pnpm dev:docs (hot reload on :4321). Fenced mermaid diagrams and relative-path images travel automatically — keep diagrams as plain fences, never screenshots. A sidebar entry pointing at a file that is not published fails the build, which is how a missed rename gets caught.