Ga naar hoofdinhoud

TDS-PORTFOLIO-001: Overlay & referentie-generator

Datum: 2026-05-19 Status: Concept

Doel​

Een lokaal script dat zusterrepos uitleest en de gegenereerde delen van Documentatie-pagina's invult: portfolio-map alinea's, portfolio-visie overlays, en API-referentie-secties. Met een schone draai verdwijnt het risico dat handgeschreven mirrors verouderen ([[PORTFOLIO-001-overlay-geen-mirror]]).

Referentie​

  • PRD: (nog geen — dit is door de visie geïnitieerd, niet door een product-PRD)
  • ADRs: [[PORTFOLIO-001-overlay-geen-mirror]]

Referentiepatroon​

~/Projects/
├── Ruimtemeesters-Documentatie/        ← deze repo
│   ├── tools/overlay-generator/        ← woont hier
│   ├── docs/60-portfolio-atlas/portfolio-map.md
│   ├── docs/00-visie/portfolio-visie.md
│   └── docs/70-api-referentie/<app>-<surface>-referentie.md
├── Ruimtemeesters-Databank/
│   ├── README.md                       ← bron
│   ├── docs/00-vision/*.md             ← bron
│   ├── openapi.yaml                    ← bron (optioneel)
│   └── mcp-tools.json                  ← bron (optioneel)
├── Ruimtemeesters-Geoportaal/
│   └── …
└── (verder alle Ruimtemeesters-* repos)

De generator draait vanuit Ruimtemeesters-Documentatie/ en leest zusterrepos via relatieve paden (../Ruimtemeesters-*). Geen HTTP, geen autorisatie nodig — alles is lokaal.

Vereiste technische eigenschappen​

Interfaces​

  • CLI: pnpm generate (of python -m overlay_generator) — geen argumenten voor de happy path; draait alle generatoren. Vlaggen: --only portfolio-map, --check (faalt als output wijzigt), --dry-run.

  • Input contract: per app een conventiegebaseerde set bestanden in een vaste plek (zie hierboven). Als een bestand niet bestaat, wordt die app gewoon overgeslagen voor die surface — niet faliekant falen.

  • Output contract: gegenereerde secties zitten tussen HTML-comment-markers in bestaande markdown-bestanden. De generator vervangt alleen wat tussen de markers staat:

    <!-- BEGIN GENERATED:portfolio-map -->
    ...
    <!-- END GENERATED:portfolio-map -->

    Alles erbuiten is handgeschreven en blijft intact.

Data​

  • Geen persistente opslag. De generator is staatloos: input is de huidige filesystem-staat, output is markdown.
  • Geen API-aanroepen. Geen Github, geen externe registries. Dit houdt de generator offline en deterministisch.
  • Caching: niet nodig in de eerste versie. Een doorloop over 25 repos is goedkoop genoeg.

Randvoorwaarden​

  • Idempotent: tweemaal draaien levert dezelfde diff. Geen tijdstempels, geen UUIDs, geen volgorde-afhankelijkheid in output.
  • Deterministisch: zelfde input → byte-voor-byte zelfde output. Anders is CI-controle (--check) nutteloos.
  • Veilig faalbaar: een ontbrekend bron-bestand levert een log-regel en een placeholder-marker, niet een crash. Een corrupte bron levert een crash mét referentie naar het bestand.
  • Onafhankelijk van app-implementaties: de generator leest alleen markdown / OpenAPI / JSON. Hij hoeft niets te installeren of te draaien uit de zusterrepos.

Surface per surface​

SurfaceBron-detectieOutputlocatieGegenereerde inhoud
portfolio-mapEerste alinea onder # <App> in elke ../Ruimtemeesters-*/README.mddocs/60-portfolio-atlas/portfolio-map.mdEén bullet of tabelregel per app
portfolio-visieEerste alinea van ../Ruimtemeesters-*/docs/{00-vision,00-visie}/*-vision.mddocs/00-visie/portfolio-visie.mdEén alinea per app met link
api-referentie:httpAanwezigheid van openapi.yaml / openapi.jsondocs/70-api-referentie/<app>-http-referentie.mdEndpoint-lijst, parametervormen, response-schema's
api-referentie:mcpAanwezigheid van mcp-tools.json of packages/*/mcp-tools.jsondocs/70-api-referentie/<app>-mcp-referentie.mdTool-naam, parameters, beschrijving

Nieuwe surfaces worden in een latere TDS toegevoegd, niet hier.

Categorisatie blijft handwerk​

De groepering in portfolio-map.md (Front doors / Beleidsbronnen / …) is geen output van de generator. Die categorisatie is een eigen-inhoud-redactionele keuze; alleen de beschrijvingen per app worden gegenereerd. De handmatige categorie-koppen en hun volgorde blijven buiten de BEGIN/END GENERATED-markers.

Buiten scope​

  • Doorlinken naar PRDs / ADRs / TDSs van zusterrepos op een diepere manier dan "hier is de repo, ga zelf kijken". Een echte cross-repo doc-graaf is een latere fase.
  • Schrijven naar zusterrepos. De generator is read-only buiten Documentatie.
  • Een eigen front-end. CLI volstaat.
  • Auto-commits of automatische PRs. De ontwikkelaar draait pnpm generate en commit zelf.

Openstaande vragen​

  • Implementatietaal: Node.js (consistent met de meeste apps) of Python (consistent met scrapers en datapipelines)? Geen sterke voorkeur — kiezen bij de implementatie. Pas geen GitHub Actions-template aan voordat dit besloten is.
  • CI-integratie: moet pnpm generate --check in CI faalbaar zijn om PRs te blokkeren met verouderde output, of is dat te veel friction in fase 1?
  • OpenAPI-conventies: niet alle apps hebben een openapi.yaml. Moet de generator ook FastAPI / Express introspecteren? Eerste versie: alleen bestandsgebaseerd; introspectie pas als de behoefte er aantoonbaar is.

Bijbehorend plan​

Te schrijven in 50-implementatieplannen/overlay-generator-plan.md zodra deze TDS goedgekeurd wordt.