Skip to content

Maintaining these docs

These docs are code: Markdown + Mermaid in the figestio-platform repo. They version-control, diff, and an agent can keep them current. GitHub renders the Mermaid blocks too, so the raw files are readable without building the site, and Cloudflare Pages redeploys on every push to main.

Preview locally

cd ~/Developer/figestio-platform
python3 -m venv .venv && source .venv/bin/activate   # first time only
pip install -r requirements.txt
mkdocs serve            # http://127.0.0.1:8000  (live reload)
mkdocs build --strict   # CI-style check: fails on broken links / bad refs

requirements.txt pins mkdocs-material, which pulls in MkDocs and the Mermaid superfences. CI runs mkdocs build --strict on every push (.github/workflows/docs.yml).

The page map

Page Holds
index.md Landing: the one big idea + where-to-start.
overview.md Container map split into auth / data planes; key properties.
glossary.md The shared vocabulary; the anchor target for cross-links.
identity.md xifrasoft.md figestio.md Per-service reference (model, endpoints, flows, config, gotchas).
clients.md The three fronts + the Tauri companion.
integration.md The figestió ⇄ xifrasoft contract + roadmap snapshot.
running-locally.md Ports, Docker/host combos, host.docker.internal, seeding.

Keeping them current

Two mechanisms work together:

  1. Convention — updating /docs is part of any cross-cutting change, the same way PLATFORM.md / INTEGRATION.md get updated as decisions settle. Each repo's CLAUDE.md points here.
  2. The docs-maintainer agent — the paste-able prompt below refreshes the affected pages + diagrams from the current code. A Stop hook in this repo nudges when source changed but /docs didn't.

The docs-maintainer agent prompt

Open a session in ~/Developer/figestio-platform and paste:

Update the platform docs in /docs to match the current code. These are MkDocs Material
pages (Markdown + Mermaid). Do not invent — read the actual code.

Read for context: PLATFORM.md, INTEGRATION.md, ~/.claude/plans/breezy-cooking-barto.md,
each repo's CLAUDE.md, and the relevant modules across ~/Developer/xifrasoft/{identity,api,front}
and ~/Developer/figestió/{api,backoffice,companion-app,front}.

Task: bring /docs/{index,overview,glossary,identity,xifrasoft,figestio,clients,integration,
running-locally}.md in line with reality — endpoints, token modes, flows, ports, env vars,
and the roadmap table on integration.md. Update the Mermaid diagrams where the shape
changed (auth flow, the tenancy ER, the file-sync pipeline, the container planes). Keep
prose tight, skimmable, and accurate; prefer fixing an existing diagram over adding one.

Verify: `mkdocs build --strict` passes (no broken links/refs) and every Mermaid block is
syntactically valid. List exactly what you changed and why. Then commit + push.

Conventions for diagrams

  • One clear diagram per concept. Split anything dense rather than cramming. Keep node labels short; put the detail in the prose around the diagram.
  • Pick the right type: sequenceDiagram for flows (auth, sync, assignment), erDiagram for the tenancy model, flowchart for architecture/data flow.

  • Theme every diagram with a %%{init: ...}%% block using the brand palette so it stays legible in light and dark mode. The site renders diagrams on a fixed light "figure card" (see extra.css), so use dark ink text on the brand tints below:

    Role Fill Stroke Text
    client / process #d9e8e7 #4f8f8d #15302f
    identity / gate #e9f0d9 #7c9a47 #283010
    API / external #f3ece6 #b39a82 #2b211b

    Set fontFamily:'Inter, system-ui, sans-serif' and lineColor:'#7d8f8e' in themeVariables, and apply the roles with classDef/class (flowcharts) or the actorBkg/noteBkg… variables (sequence diagrams). Copy an existing diagram as a starting point — they're all consistent.