TDV Client Portal — technische architectuur

Dit is een werkende scaffold, geen kant-en-klare app: de fundamenten (auth, tenancy, database schema, RLS, routing, één volledige module end-to-end) staan er echt en draaien, de overige modules uit de brief zijn als lege routes met een consistent patroon aangelegd zodat ze snel bij te bouwen zijn.

Stack

Laag	Keuze	Waarom
Framework	Next.js 14, App Router	Server Components → data blijft server-side, geen aparte API-laag nodig voor reads
Taal	TypeScript, strict mode	Fouten in tenancy-logica (welk bedrijf mag wat zien) horen compile-time gevangen te worden waar mogelijk
Styling	Tailwind CSS	Snel, en design tokens (kleur/typografie) zitten centraal in tailwind.config.ts
Database + Auth	Supabase (Postgres + Auth + Storage)	Eén platform voor DB, login, files; Row Level Security doet het zware werk voor multi-tenancy
AI / RAG	Postgres pgvector + Anthropic Messages API	Geen aparte vector-DB nodig; retrieval en generatie blijven in dezelfde infrastructuur
Hosting	Vercel	Native Next.js support, preview deployments per PR

Waarom dit datamodel

Eén regel, geen twee. In plaats van elke module (projecten, aanvragen, content, bestanden) los te beveiligen, hangt letterlijk elke tabel met klantgegevens aan companies.id, en één stel RLS-policies (is_tdv_staff() / current_company_id()) bepaalt overal wie wat mag zien. Dat betekent: een bug in een React-component kan nooit klantdata van bedrijf A tonen aan bedrijf B — de database weigert de query, niet de UI.

RLS in de database, niet "if" in de React-code. Je zal in lib/data/*.ts geen .eq('company_id', ...) filters vinden op basis van iets dat de client meestuurt. De sessie van de ingelogde gebruiker draagt zijn/haar identiteit; Postgres bepaalt de rest. Dat is de belangrijkste architecturale beslissing in dit project en zou dat ook moeten blijven bij uitbreiding.

AI-assistent leest nooit rechtstreeks. ai_documents (de RAG-kennisbank) heeft bewust géén client-facing SELECT-policy. De enige toegang loopt via de API-route app/api/ai/chat/route.ts, die zelf eerst company_id opzoekt via de ingelogde sessie en dat als verplichte parameter doorgeeft aan de match_ai_documents functie. Dubbele afscherming voor het gevoeligste stuk van het systeem.

Wat er echt werkt (volg dit patroon voor de rest)

• Auth: login, registratie, wachtwoord vergeten/resetten, sessiebeheer via cookies, middleware die elke request ververst en niet-ingelogde gebruikers naar /login stuurt — behalve op / zelf, zie hieronder.
• Landingpage (/, app/page.tsx): publieke marketing-/pricingpagina in TDV-branding, de eerste stap richting een zelfbedienbaar SaaS-product voor marketingbureaus, freelancers en agency-startups. Ingelogde bezoekers worden meteen doorgestuurd naar /dashboard (zelfde route, gewoon een redirect() in de page in plaats van middleware — middleware laat / nu als enige uitzondering door zonder sessie). Drie prijstiers (Essentieel €129, Professioneel €349, Agency €899 per maand excl. btw; interne codes starter/growth/agency), door de klant bevestigd. "Start gratis proefperiode" linkt naar het bestaande /register (14 dagen), "Inloggen" naar /login. Bewust puur presentationeel: geen Stripe, geen nieuwe tabellen, geen wijziging aan het company/tenancy-model — zie de uitleg verderop in dit bestand over waarom de echte SaaS-architectuur apart, begeleid werk blijft.
• Registratie: /register laat een nieuwe klant zelf een account + bedrijf aanmaken (naam, bedrijfsnaam, e-mail, wachtwoord) — app/(auth)/register/actions.ts. Alles (auth user, companies-rij, profiles-rij) wordt in één server action met de admin-client aangemaakt, niet via een client-side signUp() gevolgd door een losse server action — dat laatste zou een client-aangeleverde user-id vertrouwen bij het schrijven van de profielrij. Het nieuwe bedrijf start op onboarding_status = 'pending_review' (migratie 0022, standaard 'active' voor door staff aangemaakte klanten) en de klant ziet op /dashboard een "wachten op TDV"-scherm tot een staff-lid het activeert vanaf /admin/clients/[id] ("Activeren"-knop, ook zichtbaar als badge in de klantenlijst).
• Projecten: lijst + detail + opmerkingen, volledig via Server Components
  • RLS — lib/data/projects.ts → app/(portal)/projects/*.
• Aanvragen (route /aanvragen, ex-"tickets" — enkel de UI/routes zijn hernoemd, de tabel heet in de database nog steeds tickets en lib/data/tickets.ts ook): lijst, nieuw, detail + reageren. Geen eigen item meer in de klant-navigatie — een aanvraag hoort bij een project, dus die maak/bekijk je vanaf de projectdetailpagina ("Gekoppelde aanvragen" + het "+"-knopje, dat naar /aanvragen/new?project=<id> linkt en het project vooraf invult). en blijven gewoon bestaan als routes, ook zonder projectcontext.

Wat nog moet worden bijgebouwd

Backlog voor de doorlopende 5-uurlijkse routine (zie onder) — één afgebakende PR per punt, in deze volgorde:

• Performance-audit, vervolg: optimistic UI voor de status-dropdowns, de ontbrekende indexen en de N+1-thumbnails zijn gedaan (zie "Wat er echt werkt" hierboven) — vervolg op de regio-fix (zie "Performance" hieronder) zodra er een nieuwe trage plek gevonden wordt.

Testaccounts

Aangemaakt met akkoord van Thomas (28/10), om op te ruimen zodra ze niet meer nodig zijn. Wachtwoorden staan nergens in de repo of in berichten.

• Test – Claude — [email protected], rol client_member, in het fictieve bedrijf Demo – Atelier Noord (fictief) (slug demo-atelier-noord) onder de TDV-agency. Bevat fictieve demo-inhoud (3 projecten, 4 content-items, 1 aanvraag) voor screenshots; de hero op de landingspagina (public/brand/portaal-demo-projecten.png) komt hiervan. Opruimen: het bedrijf met die slug en zijn rijen, en de auth-gebruiker.

Begeleide punten (niet voor de routine, met Thomas uitwerken)

• Eigen privacybeleid en voorwaarden voor het portaal (SaaS/verwerkersovereenkomst). Tot dan linkt de footer van de landingspagina naar de algemene teksten op tdvmarketing.be.

Multi-tenant white-label architectuur (actief traject, niet voor de onbemande routine)

De landingspagina belooft een white-label SaaS (andere agency's/freelancers krijgen een eigen afgeschermde, zelf-gebrande omgeving, met een abonnement erbovenop) maar /register leverde dat tot nu toe niet — het maakte gewoon een nieuwe klant aan onder TDV's eigen, enige tenant. Dit wordt stap voor stap rechtgezet via 6 losse, elk apart geverifieerde PR's (plan: /root/.claude/plans/whimsical-sauteeing-crayon.md in de sessie die dit traject startte) — raakt "de belangrijkste invariant" hierboven beschreven, dus expliciet niet voor de onbemande routine, elke stap begeleid:

1. agencies-tabel + backfill van bestaande data naar TDV als Agency #1 (migratie 0025) — schema-only, geen gedragsverandering.
2. Rolnaam-hernoeming tdv_admin/tdv_staff → agency_admin/agency_staff (migratie 0026 + ~15 bestanden, in dezelfde release).
3. Agency-bewuste RLS-herschrijving (migratie 0027/0028) — is_tdv_staff() vervangen door is_agency_staff() + current_agency_id() in alle policies, inclusief twee bestaande losstaande gaten (profiles_select_staff_public, social_accounts hadden al géén enkele scoping).
4. Agency-zelfregistratie (/register maakt een agencies-rij, directe trial, geen betaalstap) + vijf onveilige "notificeer alle staff"-queries scopen op agency.
5. Per-agency branding: logo, weergavenaam en accentkleur zijn DB-gedreven (agencies.logo_url/brand_name/accent_color, migratie 0032), instelbaar via /admin/settings → Branding. Sidebar/MobileNav/admin- layout tonen het agency-logo i.p.v. het hardcoded TDV-logo; --color-accent (CSS custom property, lib/color.ts) overschrijft Tailwind's accent-token runtime, met TDV's terracotta als fallback. Vervolg: achter de login zijn <title>, favicon/Apple-touch-icon (favicon_url, anders logo_url) en theme-color (accent_color) ook per agency (lib/branding-metadata.ts, generateMetadata/ generateViewport in de (portal)/(admin)-layouts); TDV blijft de fallback en is wat /login, /register en de landingspagina tonen. Bewust TDV-vast gebleven: opengraph-image.png/OG-tags — crawlers komen zonder sessie binnen, dus per-agency kan daar pas met een eigen domein per agency (agencies.custom_domain). Ook het PWA-manifest (app/manifest.ts: naam, icoon, theme_color) volgt de agency van de ingelogde gebruiker, want de manifest-fetch draagt de sessie mee (crossorigin="use-credentials"); anoniem of zonder eigen branding blijft het TDV. Het favicon is apart te uploaden in → Branding (PNG/SVG/ICO, hoogstens 512 KB, zelfde bucket ); zonder favicon geldt het logo.

Performance

vercel.json pint serverless functions op fra1 (Frankfurt) vast. Het Supabase-project draait in eu-central-2 (Zürich) — zonder deze pin viel Vercel terug op zijn default iad1 (US-oost), wat elke server-side Supabase-call (elke paginalaad, elke Server Action) een transatlantische heen-en-terugreis liet maken in plaats van een paar honderd kilometer. Dat was de hoofdoorzaak van een traag aanvoelend portaal — niet iets dat een andere hostingprovider zou oplossen, wel iets dat elke andere EU-gehoste backend al automatisch goed zou hebben.

Setup

npm install
cp .env.example .env.local   # vul Supabase- en Anthropic-sleutels in

npx supabase login
npx supabase link --project-ref <project-ref>
npx supabase db push          # past supabase/migrations/*.sql toe

npm run db:types              # genereert types/database.types.ts uit het echte schema
npm run dev

Mappenstructuur

app/
  (auth)/login/            → publieke auth-routes
  (portal)/                → alles achter login, gedeelde sidebar-layout
    dashboard/ projects/ aanvragen/ content-planning/
    files/ ai-assistant/ notifications/ settings/
  (admin)/admin/           → TDV-staff-only, eigen layout + rolcheck
  api/ai/chat/             → RAG endpoint
  api/webhooks/supabase/   → plek voor bv. Storage/Auth webhooks
lib/
  supabase/                → client/server/middleware helpers (RLS-bewust)
  data/                    → server-only data access per module
components/
  layout/                  → Sidebar, (nog toe te voegen: Topbar)
  ui/ dashboard/ projects/ aanvragen/ → per-module presentatie­componenten
supabase/
  migrations/0001_init.sql     → volledig schema + RLS voor elke module
  migrations/0002_ai_search.sql → pgvector RPC voor de AI-assistent
types/
  database.types.ts   → placeholder, vervang via `npm run db:types`
  domain.ts           → handgeschreven types die de UI gebruikt

Design tokens

De huisstijl volgt de huisstijlrichtlijnen van tdv. marketing (v1.1), opgesteld door de design-sessie:

• tailwind.config.ts: alle kleurrollen (canvas, surface + -sunken/ -raised, border + -strong, ink #282828 + -muted/-subtle), de statuskleuren new/progress/waiting/done/danger (elk met soft en on voor pills), titelgroottes (text-display/h1/h2/h3/label), radius en schaduwen. Componenten gebruiken nooit hex-codes.
• lib/brand/accent.ts: leidt uit één accentkleur (agencies.accent_color, anders TDV-terracotta) alle accent-tokens af — accent, accent-fg (wit of #282828 volgens luminantie), accent-dark (hover), accent-soft, accent-text — volgens de HSL-regel uit de richtlijnen, met gegarandeerd WCAG AA. Te lichte kleuren worden automatisch verdonkerd. In /admin/settings → Branding toont het formulier live wat het portaal met de gekozen kleur doet (knop en link, licht en donker), met een melding als de kleur verdonkerd wordt.
• app/globals.css: de basisklassen .btn-*, .input, .card, .focus-ring, .link.
• components/brand/: het woordmerk en monogram als React-component (letters in currentColor, punt altijd terracotta) en AgencyLogo (agency-logo → agency-naam → TDV-woordmerk).
• Titels: Epilogue 600, kleine letters met punt (brandTitle() in lib/utils.ts doet dat voor dialog- en lege-staat-titels). Pagina- en sectietitels in de app staan rechtstreeks zo in de code ("dashboard.", "vraagt je aandacht."): paginatitel font-display text-h2 sm:text-h1, sectietitel font-display text-h3. Dynamische titels (een projectnaam, klantnaam, …) blijven zoals ingevoerd.
• Kaarten krijgen geen gekleurde zijbalk; status toont een Badge.
• Dark mode: standaard volgt het portaal de systeeminstelling; in /settings → Weergave kiest de gebruiker Systeem, Licht of Donker. De keuze staat in de cookie tdv-theme (lib/theme.ts) en de (portal)/(admin)-layout zet de class server-side op haar wrapper (dark of theme-system), dus geen lichte flits bij het laden. De publieke pagina's (landing, /login, /register) blijven altijd licht.