RPO Architecture Proposal

Project: Risicoplatform Overheden (RPO) — VNG Risicobeheer Author: Architect, vanmiddag-decision-support Date: 2026-05-28 Status: Draft voor meeting 12:00–17:00 Nijmegen Scope: Architectuur beyond de live demo (https://rpo.humanaize.nl) — naar productie per 1 juli 2026

This document is decision-support, not a finished spec. Doel: 6 architectuur-besluiten landen vanmiddag, niet 60 opties uitleggen.

0. Executive summary — de 6 architectuur-decisies

Hard deadlines die de scope dicteren:

• 1 juli 2026 (~5 weken) — auth + persistente data + zichtbare website voor accountmanager
• Aug 2026 — EU AI Act ingangsdatum
• Okt 2026 — RPO-congres, 200 gemeenten / 4 actieve werkgroepen KPI

Default principe per sectie: "wat ships voor 1 juli, wat schuift naar v1.1."

1. System overview

Narrative. Eén Next.js applicatie draait op de bestaande droplet onder PM2 (rpo-vng), met nginx als TLS-termination. Auth gaat via Auth0 (HumanAIze-default). Persistente data zit in DigitalOcean Managed Postgres — geen Supabase, om binnen de stack te blijven. Drie AI-werkstromen leven naast de applicatie maar communiceren via Postgres: (a) een dagelijkse journalist-agent als Python cron-worker, (b) Mano's Ask Humanize research-agent als SaaS-integratie met scoped SharePoint-toegang, (c) een one-off marktonderzoeker + marketingstrateeg pipeline in tools/research/ die markdown produceert die in de repo gecheckt wordt. Secrets centraal in Azure Key Vault zoals de overige HumanAIze-projecten.

2. De twee-persona AI-laag (marktonderzoeker + marketingstrateeg)

Mano, 27 mei: "Het is echt een marketingonderzoeker, marktonderzoeker. Een marktonderzoeker kan wel aanbevelingen doen, maar een stratege kijkt verder dan alleen het marktonderzoek."

Architectuur-positie: dit is geen deployed service. Het is een one-off content-generation pipeline die één keer (en eventueel kwartaal-iteratief) wordt afgevuurd om de doelgroep-portret + waardepropositie te genereren. Output landt als markdown in de repo (bron voor src/lib/content.ts en de positionerings-doc), niet als runtime endpoint.

Argument: Mano heeft die output één keer nodig voor de 1-juli launch. De waardepropositie verandert niet wekelijks. Bolting dit in de Next.js runtime betekent productie-engineering voor iets dat een notebook kan zijn.

2.1 Marktonderzoeker

Prompt-pattern (1-shot extractie):

SYSTEM: Je bent een ervaren marktonderzoeker met 20+ jaar in risicomanagement bij Nederlandse gemeenten.
Je leest scraped HTML + tekstfragmenten en extraheert: (1) doelgroep-vocabulaire,
(2) pijnpunten, (3) thema-frequentie, (4) gebruikte tools/methoden.
GEEN aanbevelingen, GEEN strategie — alleen observatie.

USER: <bundel van 30-50 scraped fragments + metadata>

2.2 Marketingstrateeg

Handoff. Sequentieel, human-in-the-loop. De strateeg wordt pas gedraaid nadat Mano het doelgroep-portret heeft gelezen en eventueel handmatig aangevuld. Geen automatische trigger.

2.3 Wat ships voor 1 juli

• Pipeline runt één keer in juni
• Output wordt door Mano gereviewed in week 24
• Commits landen in src/lib/content.ts zodat de website-copy verbatim doortikt naar productie
• Geen API, geen UI, geen scheduler

2.4 Wat schuift naar v1.1

• Kwartaal-refresh als cronjob (vraagt scheduler + storage van diffs)
• UI in admin-route voor Mano om scrape-bronnen te beheren

3. Journalist-agent vs. Ask Humanize research-agent

Johan, 27 mei: "Je zou eigenlijk ook kunnen zeggen dat je ook een beetje een journalist eigenlijk, hè." Mano, 27 mei: "Ik vind dat echt een briljant idee."

Decision-vraag 6 in de briefing: één agent of twee?

3.1 Aanbeveling: SPLIT

Twee aparte services, met gedeeld schema (pijler-classificatie, dedup-fingerprint), geen gedeelde runtime.

3.2 Argumentatie (vier dimensies)

Coupling-risico bij one-agent-model: je bouwt een single point of failure voor twee onafhankelijke functies, met een deadline van 5 weken. Een outage in de SharePoint-integratie zou de publieke leden-feed plat leggen. Niet doen.

Wat wel delen: het schema. Beide agenten produceren items met dezelfde shape:

type FeedItem = {
  id: string;            // fingerprint hash (url + title + datum)
  source: string;        // 'binnenlandsbestuur' | 'sharepoint:rpo' | ...
  pijler: 'ravijn' | 'sociaal' | 'cyber' | 'fraude' | 'vastgoed' | 'overig';
  subthema: string[];    // dynamisch aangescherpt (zie Aanscherpen-stap)
  titel: string;
  samenvatting: string;  // LLM-generated, 2-3 zinnen
  url: string;
  publishedAt: Date;
  confidence: number;    // pijler-classificatie confidence 0-1
  audience: 'public' | 'internal';
};

3.3 Journalist-agent runtime

Type: dagelijkse cron worker. Niet event-driven (sources publiceren op onvoorspelbare momenten; polling is goedkoop genoeg). Niet on-demand (frisheid is feature).

Bronnen (deze landen als config in tools/journalist/sources.yaml, niet hardcoded):

• RSS waar beschikbaar (Binnenlands Bestuur, VNG, NCSC, EUR-Lex search-feeds)
• HTML-scrape met httpx + selectolax waar geen RSS (IBD-meldingen, ESB)
• Custom: EUR-Lex CELEX-zoektermen op gemeente, AI Act, cyberbeveiligingswet

Aanscherpen (Johan's centrale eis: thema-definities moeten groeien, niet bevriezen).

Implementatie: na elke classify-batch berekent de agent welke subthema-strings ≥3× per week opduiken binnen een pijler. Die landen in pijler_subthemes tabel, zichtbaar in admin-UI, met optie "promote to top-level subthema". Mens-in-the-loop: agent stelt voor, mens (Mano of moderator) bevestigt.

Storage. Postgres, geen vector-DB. De volumes zijn klein (~50-200 items/dag), full-text search via tsvector is adequaat, en pijler-classificatie is een symbolisch label (geen embedding-similarity nodig). Vector-search alleen toevoegen als semantic search over werkgroep-content een feature wordt — dat is v1.1.

Modelkeuze. Claude Sonnet 4.5 voor classify (kosten-optimaal, snel). Opus alleen voor weekly digest-samenvatting als die ooit een feature wordt.

3.4 Ask Humanize research-agent runtime

Mano-owned, configured via Ask Humanize UI. Geen eigen build vanuit ons team. Architectuur-implicatie voor ons:

• We exposen geen direct endpoint richting Ask Humanize
• Ask Humanize krijgt read-only SharePoint-toegang scoped per project (RPO + RBF apart)
• Output van research-agent landt als markdown/Word in een SharePoint-export-map, die Mano handmatig binnen-curateert
• Niet automatisch op de publieke feed — anders krijg je SharePoint-lekken op het portaal

Secrets. Ask Humanize-tenant credentials in Azure Key Vault onder humanaize/ask-humanize/rpo-research. SharePoint scoping via Azure AD app-registration met Sites.Selected permission (whitelist alleen RPO-map).

3.5 Wat ships voor 1 juli

• Journalist-agent v0: 3 bronnen (BB, NCSC, IBD), dagelijkse cron, output naar Postgres, simpele feed-UI op /platform/actualiteiten
• Aanscherpen alleen als dashboard-view (geen automatische promotie van subthema's)
• Ask Humanize: Mano configureert standalone, geen UI-integratie aan onze kant

3.6 Wat schuift naar v1.1

• 6-10 extra bronnen
• Auto-promotion van subthema's
• Member-personalized feed (filter op gekozen pijlers uit onboarding)
• Email digest per werkgroep

4. Frontend architecture beyond the demo

4.1 Stack-uitbreiding (additief, geen rewrite)

Huidige stack: Next.js 15 + React 19 + Tailwind + Motion. Blijft als basis.

4.2 Auth-positie

• Auth0. Authentik considered-and-rejected: self-hosting auth toevoegen aan een team-of-1-ops voor 5 weken deadline is risk-additive zonder duidelijke gain.
• Gemeente-medewerkers krijgen in v0 een invite-based magic-link flow. Auth0 Universal Login + email-OTP. Geen wachtwoorden tot enterprise-SSO komt.
• Rollen: member, moderator, admin. Geen gemeente-niveau permissies — content is binnen het platform open voor alle leden.

4.3 Peer-matching algoritme (sketch)

Uit ONBOARDING flow (content.ts:587): member kiest 3 thema's, krijgt 3 matches. Algoritme v0:

def match(user):
  candidates = users.where(
      gemeente != user.gemeente,        # cross-gemeente voorkeur
      thema_overlap(user, candidate) >= 1
  )
  return sorted(candidates,
      key=lambda c: (
          jaccard(user.themas, c.themas),   # thema-overlap
          c.recent_contribution_score,      # actieve users boven
          -distance(user.regio, c.regio)    # regio-nabijheid als tiebreaker
      ),
      reverse=True
  )[:3]

Geen ML, geen embeddings — Jaccard + activity score is genoeg voor v0. Belangrijker: thema-keuzes moeten editbaar zijn na onboarding (anders bevriest het matchmodel).

4.4 Werkgroep-functionaliteit

Per VIER_SPOREN[3] (Platform-spoor) en PIJLERS[*].werkgroep: vijf werkgroepen, 1-op-1 met pijlers (default uit briefing decision-vraag 4).

v0-features per werkgroep:

• Threaded discussies (zoals klassiek forum, geen Slack-stijl chat — risicomanagers zijn geen always-on)
• Pinned resources (links naar SharePoint-docs of upload)
• Member-list met thema-tags
• Upcoming meetup (één event-record per werkgroep)

Niet v0: voice/video, DM, polls, gamification. Te veel surface voor 5 weken.

4.5 Search-strategie

Eén index, twee filters. Postgres FTS over één searchable_content materialized view die zowel feed_items (actualiteiten) als forum_posts (werkgroep-content) bevat, met source_type als filter. Dit voorkomt twee aparte search-UIs en houdt relevance-ranking consistent.

CREATE MATERIALIZED VIEW searchable_content AS
SELECT id, 'feed' AS source_type, titel, samenvatting AS body, pijler, published_at
FROM feed_items
UNION ALL
SELECT id, 'forum' AS source_type, subject, body, werkgroep_id::text, created_at
FROM forum_posts;

CREATE INDEX idx_searchable_fts ON searchable_content
  USING gin(to_tsvector('dutch', titel || ' ' || body));

Refresh hourly via cron.

4.6 Wat ships voor 1 juli

• Auth0 + invite-flow voor 20-50 pilot members
• 5 werkgroepen met forum-threads + member-list
• Onboarding-flow zoals in prototype
• Actualiteiten-feed op /platform (read-only, journalist-agent output)
• Geen peer-matching nog — /onboarding step 3 stuurt naar werkgroep-list i.p.v. matches

4.7 Wat schuift naar v1.1 (na 1 juli)

• Peer-matching (vraagt ~50+ users om zinvol te zijn)
• File-upload naar Spaces (eerst SharePoint-links volstaan)
• Search-UI (eerst direct naar werkgroep navigeren)
• Email-digest

5. Deployment + infra

5.1 Huidige situatie

• Test droplet 157.245.67.48, PM2 process rpo-vng, nginx + Let's Encrypt, deSEC DNS rpo.humanaize.nl
• Geen DB, geen auth, geen secrets (statisch prototype)

5.2 Productie-target per 1 juli

Blijf op droplet. Voeg toe:

Eerste-jaar-ballpark: €4-5k. Plus de marktonderzoeker/strateeg one-off (~€50-100 in API kosten, eenmalig).

5.3 Wanneer migreren? (niet een datum maar een trigger)

Geen K8s in v1 en v1.1. De gemeente-doelgroep is begrensd (max 341 gemeenten × ~5 users = ~1700 max-users levenscyclus). Droplet + managed PG schaalt daar makkelijk doorheen.

5.4 Deployment-flow

Per-1-juli kritiek pad:

1. Provisioneer Managed PG (1 dag)
2. Auth0 tenant configureren + invite-flow (2 dagen)
3. Prisma schema + seed (2 dagen)
4. Werkgroep + forum routes (5 dagen)
5. Journalist-agent v0 (3 dagen)
6. Onboarding-flow productionizen (3 dagen)
7. Buffer + bug-bash (5 dagen)

• Totaal: ~21 werkdagen, marginaal binnen 5 weken bij focus.

6. Integration boundaries

6.1 SharePoint / M365 via Ask Humanize

• Toegang: Azure AD app-registratie met Sites.Selected (niet Sites.Read.All!). Mano whitelist per site-collection
• Scope per project: Risico Platform Overheden/ voor RPO research-agent, Risico Beheer Fonds/ voor RBF
• Credentials: Azure Key Vault, secret-rotation 90-dagen via Azure-policy
• Data-flow: read-only naar Ask Humanize. Output landt als markdown/Word terug in SharePoint, niet rechtstreeks in onze Postgres. Mano cureert handmatig wat er publiek mag

Waarom geen directe SharePoint→portaal-pipe? Permissiestructuur van SharePoint is complex (per-folder, per-doc, member-of-group). Doorlopend correct enforcen vanaf onze app is een security-projectje van weken. Mano-curatie is goedkoper en correcter voor v1.

6.2 VNG / Christiaan Ravensbergen

Voorlopig standalone. Geen directe VNG-systeem integratie in v0/v1.

Concreet vragen aan Christiaan vanmiddag: kunnen we een eenmalige CSV-export krijgen van de 169 gemeente-contacten met email? Dat is voldoende voor invite-flow.

6.3 RBF parallel traject

Volledig gescheiden stack voor de PoC-fase, shared services waar dat gratis is.

Schemarefactor: als de journalist-agent v0 al multi-tenant op project_id wordt gemodelleerd, kost RBF-uitbreiding later weinig. Aanbeveling: doe het meteen multi-tenant in de DB, ook al gebruikt RPO-v0 maar één tenant.

7. Risico's & open vragen

7.1 Te beslissen vanmiddag (anders staat het bouwen vanaf maandag stil)

7.2 Te deferren tot na 1 juli

• Peer-matching (vereist users)
• Email digest
• File-upload UI
• VNG-SSO
• Subthema auto-promotion
• Multi-region, K8s, vector-search

7.3 Onzichtbare risico's die naming verdienen

8. Sequence diagram — concrete user-flow

Scenario: Marieke, risicomanager in Apeldoorn, opent het platform 's ochtends. Ze ziet nieuwe actualiteiten van de journalist-agent (incl. IBD-melding over ransomware in Brabant), klikt door naar de werkgroep Cyber, en stelt een peer een vraag.

Wat dit diagram laat zien:

• Journalist-agent draait decoupled van user-requests (cron in de ochtend, niet on-demand bij page-load)
• Read-path is plain SQL — geen LLM in user-request critical path
• LLM-calls (Anthropic) zitten alleen in background-jobs
• Auth0 zit alleen in middleware, niet in elke API-call (sessie cached)
• Email-notifications via Resend gaan async (Postgres NOTIFY → background worker)

9. Wat niet in dit document zit (bewust)

• Branding/visueel ontwerp — buiten architectuur-scope
• Inhoudelijke pijler-discussie — dat is decision-vraag 1 in de briefing, niet architectuur
• Detailed seed-data — komt in prisma/seed.ts
• RBF-specifieke architectuur — krijgt eigen doc nadat PoC-bouwplan v3.0 (SharePoint Risico Beheer Fonds/2. CRM informatie/bouwplan fase 1 poc/) gereviewed is
• GDPR/DPIA — moet apart traject, juridisch lead. Aanbeveling: pre-launch lichte DPIA (member-data, journalist-agent classificaties)

10. Beslismomenten — gecondenseerd

Vanmiddag in Nijmegen (12:00–17:00):

1. Akkoord op SPLIT-architectuur journalist-agent vs Ask Humanize? → unblocks bouw vanaf maandag
2. Akkoord Auth0 + Managed PG provisioneren deze week? → unblocks data-model
3. Werkgroep = pijler 1-op-1? → unblocks routes + schema
4. CSV-roster vraag aan Christiaan? → unblocks invite-flow
5. Journalist-agent v0 met 3 bronnen oké voor 1-juli? → bepaalt bouw-budget
6. Domein blijft rpo.humanaize.nl voor v1? → unblocks Auth0-config

Bij ja-ja-ja-ja-ja-ja is dit document gepromoveerd van proposal naar spec, en kan Stijn maandag scaffolden.

Referenties:

• /home/stijn/coding/rpo-vng/Briefing.md — TL;DR + decision agenda
• /home/stijn/coding/rpo-vng/src/lib/content.ts — transcript-derived content (BLAUWE_FAMILIE, VIER_SPOREN, ONDERZOEK_PERSONAS, JOURNALIST_AGENT, BRAINSTORMS, ONBOARDING, FAMO_VS_RPO)
• Live demo: https://rpo.humanaize.nl
• Repo: git@github-stijnfs:HumanaizeNL/rpo-vng.git