Developer Guide

1. Quick Start

2. Lokale URLs

Tenant Admin — directe links (lokaal)

Vervang demo-premium door een andere tenant ID. Eén /admin/ path voor alle tiers — tier komt uit het tenant document.

3. Tenant Sites bouwen

4. Staging Omgeving

5. Productie Omgeving (cocinia-3679c)

Hosting sites

Custom domeinen (in verificatie)

Firebase Auth

• Email/Password provider ingeschakeld
• Platform admin: webandallwebdesigns@gmail.com — platformAdmin: true claim gesynced via onUserWrite Firestore trigger
• Web app SDK config: app ID 1:891036335605:web:bb9938bd2b9e73c7c474bc, API key AIzaSyBS3p7arM9KWKF_DFKDbwFM8eTuqEbxZwY

Email domeinen

• Resend domein geverifieerd: replies.cocinia.be
• API key: restricted tot replies.cocinia.be (Sending access only)
• Inbound webhook URL: https://oninboundemail-eegvljpyaq-ew.a.run.app
• Platform-mails from: noreply@replies.cocinia.be
• Tenant-mails from: tijdelijk ook noreply@replies.cocinia.be — zie #117 voor per-tenant domein (launch-blocker)
• Facturen from: facturen@replies.cocinia.be

Secret Manager

Firestore

• Database: propere lei sinds 2026-04-26 — backup op gs://cocinia-3679c.firebasestorage.app/backups/
• Indexes: firestore.indexes.json is single source of truth (deploy via firebase deploy --only firestore:indexes)
• Tenants: demo-premium aanwezig als test tenant

Hosting deploy volgorde

6. Tenant aanmaken flow

1. Wizard in platform admin (/platform-admin/tenants/new/) — vult basisgegevens, tier en owner email in.
2. createTenant callable schrijft het tenant document, stuurt een invite en roept provisionHostingSite aan.
3. provisionHostingSite maakt automatisch de Firebase Hosting site aan: cocinia-{id} op productie, cocinia-staging-{id} op staging.
4. buildReady Firestore trigger detecteert de nieuwe tenant en dispatched de GitHub Actions build-tenant workflow (repository_dispatch, type build-tenant).
5. GitHub Actions bouwt apps/tenant-site + apps/tenant-admin met de juiste TENANT_ID en FIREBASE_PROJECT_ID, en deployt naar de hosting site van de tenant.
6. Deployment status wordt teruggeschreven in tenants/{id}/deployments/latest.

Handmatig rebuilden kan via de Build and Deploy Tenant workflow (Actions tab) met tenant_id en optioneel project_id.

7. E2E Tests

Zie TESTING_GUIDE.md voor fixtures, tier-testing en data-test attributen.

8. Poorten Overzicht

Migratiebron emulator (port 8282) wordt ad-hoc gestart voor data-import van een legacy project (bv. denotelaar-7a8d2): firebase emulators:start --config .denotelaar-emulator.json --project denotelaar-7a8d2 --only firestore --import=./database_export.

9. Troubleshooting

11. Email functies

Alle uitgaande mail loopt via Resend. Op staging worden recipients automatisch geredirected naar DEV_EMAIL zodat geen echte klanten gemaild worden.

Configuratie per omgeving

Secret Manager: instellen met echo "VALUE" | firebase functions:secrets:set NAME --project=cocinia-staging --data-file=-. Elke functie die de secret gebruikt moet secrets: ['NAME'] in de function options hebben staan, anders injecteert Firebase v2 de waarde niet in process.env op runtime.

21 Cloud Functions die Resend gebruiken

Twee functions hebben óók REPLY_HMAC_SECRET nodig (geel) — ze genereren of parsen reply-addresses via messaging/reply-address.js.

Inbound email — wanneer een klant replyt

Wanneer een klant antwoordt op een email van het restaurant, vangt COCINIA die reply op via Resend en toont hem in de berichten-tab van de tenant-admin. Het restaurant ontvangt twee dingen:

1. Een notificatie email in hun gewone mailbox (op tenants/{id}/settings/general.email) met preview + link naar admin berichten-tab
2. De reply staat zichtbaar in de berichten-tab van de admin als nieuwe inbound entry op de thread

Klant replyt op email
  → Reply gaat naar: replies+ct_{tenantId}_{contactId}_{hmac}@replies.cocinia.be
  → Resend ontvangt op MX record voor replies.cocinia.be
  → Resend stuurt webhook POST naar onInboundEmail Cloud Function
  → Function verifieert Svix signature + parseert HMAC
  → Body opgehaald via resend.emails.get(emailId)
  → Quoted text gestript (cleanEmailBody)
  → Reply opgeslagen in Firestore (thread arrayUnion)
  → Status 'new' + readAt = null
  → Notificatie email verstuurd naar settings/general.email
     met preview van de reply + link naar admin berichten-tab

Reply-To mechanisme

Wanneer het restaurant een bericht stuurt via de admin, krijgt de klant een email met:

• From: noreply@replies.cocinia.be (of het tenant from-adres)
• Reply-To: replies+ct_{tenantId}_{contactId}_{hmac}@replies.cocinia.be

Het restaurant-email adres blijft privé — de klant ziet alleen het replies.cocinia.be adres. De HMAC in het reply-to adres zorgt voor veilige thread-attributie zodat een reply altijd bij het juiste gesprek terechtkomt.

From-adressen per mail-type (productie)

Platform-mails (van COCINIA naar tenant)

Tenant-mails (van restaurant naar klant)

Alle tenant-mails gebruiken dezelfde senderEmail fallback-logica (in functions/src/shared/tenant-helper.js):

tenant.senderEmail
  || tenant.email.senderEmail
  || `noreply@${tenantId}.cocinia.be`  // ← tijdelijk, zie issue #117

Type-specifiek: contactformulier bevestiging, cadeaubon (met PDF), reservatie ontvangst/bevestiging/weigering/herinnering, annulering, nieuwsbrief welkom, nieuwsbrief versturen — alle deze gebruiken senderEmail of fallback richting de klant.

DNS-configuratie in one.com

Voor replies.cocinia.be (productie)

Voor replies-staging.cocinia.be (staging): zelfde structuur maar met replies-staging als subdomein prefix.

Per-tenant email setup (issue #117)

Optie A — Eigen restaurantdomein (aanbevolen)

Gebruik het bestaande domein van het restaurant, bv. noreply@restaurant-denotelaar.be. Voordeel: professioneel, klant herkent het restaurant. Vereiste: toegang tot DNS van het restaurantdomein.

1. Resend → Domains → Add domain — voer het restaurantdomein in. Regio: Ireland (eu-west-1).
2. DNS records toevoegen bij de DNS-provider van het restaurant:

   TXT  resend._domainkey.{domein}    [DKIM waarde uit Resend]
   MX   send.{domein}                 feedback-smtp.eu-west-1.amazonses.com  (prio 10)
   TXT  send.{domein}                 v=spf1 include:amazonses.com ~all

   Bij one.com: gebruik v=spf1 include:amazonses.com include:_custspf.one.com ~all

3. Wachten op verificatie in Resend (5-30 minuten, soms tot 24u)
4. Resend API key uitbreiden — productie key moet ook {restaurantdomein} als toegestaan domein hebben (of nieuwe restricted key per tenant — veiliger maar meer werk)
5. Firestore instellen:

   tenants/{tenantId}/settings/general.senderEmail = "noreply@restaurant-denotelaar.be"

6. Rebuild tenant-admin zodat de nieuwe instelling actief is

Optie B — COCINIA subdomein

Gebruik noreply@{tenantId}.cocinia.be, bv. noreply@de-notelaar.cocinia.be. Voordeel: geen toegang tot extern domein nodig. Nadeel: klant ziet een cocinia.be subdomein in plaats van het restaurantdomein. Stappen identiek aan Optie A maar met het subdomein op one.com voor cocinia.be.

Wat als restaurant geen eigen domein heeft

Tijdelijke fallback (huidig gedrag): zolang er geen senderEmail ingesteld is, gaan alle tenant-mails via noreply@replies.cocinia.be. Werkt technisch maar niet ideaal voor branding — klant ziet COCINIA, niet het restaurant. Optie B is dan de beste route — geef het restaurant een COCINIA subdomein.

Checklist bij nieuwe tenant aanmaken

• [ ] Tenant aangemaakt via platform-admin wizard
• [ ] Email-domein kiezen: eigen domein of {tenantId}.cocinia.be subdomein
• [ ] Domein toevoegen in Resend en verifiëren
• [ ] DNS records toevoegen bij DNS-provider
• [ ] senderEmail instellen in Firestore (tenants/{tid}/settings/general)
• [ ] email instellen in tenants/{tid}/settings/general — vereist voor inbound-reply notificaties (zie stille-fail waarschuwing)
• [ ] Testen: stuur testmail vanuit berichten-tab in admin
• [ ] Verifieer dat mail aankomt en from-adres correct is

Speciale mailboxen

Probleemoplossing

12. Peppol / Maventa e-facturatie

Cocinia stuurt zijn eigen abonnementsfacturen door Peppol via Maventa als access point. UBL Peppol BIS Billing 3.0 wordt al gegenereerd door de bestaande invoice-pipeline; deze laag verzorgt het transport. Tenants zonder Peppol-ID krijgen alleen de PDF email (huidig gedrag — geen breaking change).

Architectuur

Firebase Secrets (cocinia-staging)

Toggles & vlaggen

Lokale scripts

Status lifecycle (peppolStatus)

Bekende beperkingen

Troubleshooting