Reviews Documentatie

Welkom bij de Reviews Module

Deze module is het centrale dashboard voor alles rond Google Reviews van NaNoi. Het haalt automatisch reviews op, vertaalt ze naar vier talen, analyseert elke reviewer met AI, en helpt je om snel en persoonlijk te reageren — allemaal vanuit één overzichtelijk scherm.

De reviews op de homepage worden automatisch bijgewerkt. Je hoeft zelf nooit handmatig reviews te kopiëren of te vertalen. Het systeem draait grotendeels op de achtergrond — jij hoeft alleen in actie te komen bij reviews die aandacht nodig hebben (3 sterren of minder) of nog onbeantwoord zijn.

Wat kan je met dit dashboard?

📊 In één oogopslag zien hoeveel reviews je hebt, wat het gemiddelde is, en welke aandacht nodig hebben
🤖 AI-antwoorden genereren voor onbeantwoorde reviews — altijd in het Nederlands, in "wij"-vorm, met "u"
🔍 Gasten herkennen — het systeem koppelt reviews automatisch aan reservaties
🌐 Vertalingen beheren — reviews verschijnen in de juiste taal op de homepage (NL, EN, FR, DE)
⚙️ Schedule beheren — pauzeren, hervatten, of aanpassen hoe vaak reviews gesynced worden
📈 Analytics bekijken — rating-verdeling, trends, en AI-gegenereerde tags

Waarom deze module uniek is

De meeste restaurants gebruiken een Google Reviews widget — een statisch blokje dat "laadt" en hooguit wat sterren laat zien. Of ze gebruiken dure SaaS-tools zoals Birdeye, Trustpilot of Sprout Social die $100-$500 per maand kosten.

Wat NaNoi heeft is fundamenteel anders:

Standaard restaurants	NaNoi Reviews Module
Google iframe widget — statisch, traag	Eigen sync-engine via Apify → Supabase pipeline
Geen vertalingen	AI vertaalt élke review naar NL, EN, FR, DE — homepage toont de juiste taal per bezoeker
Handmatig reageren op Google Maps	AI genereert concept-antwoord in 1 klik — jij checkt, kopieert, plakt
Geen analytics	Interactieve grafieken mét click-to-filter — klik een staaf en zie de reviews
"Wat anderen zeggen"	Reviews beheerd én vertaald in 4 talen — homepage toont de juiste taal per bezoeker
Geen koppeling met reservaties	Detail modal checkt automatisch of deze gast bekend is uit de reservatie-database
Nul automatisering	Health dots, overdue alerts, realtime toast-popups bij slechte reviews
Alleen desktop	Dark mode (OS-auto), responsive, werkt op tablet en telefoon
$100-500/maand SaaS	$0,50/maand aan AI- en Apify-kosten, rest is eigen infra

Dit is geen "reviews widget". Dit is een mini-SaaS product dat toevallig voor één restaurant draait. Gebouwd op Cloudflare Workers (serverless), Supabase (database), Apify (scraping) en DeepSeek (AI) — allemaal binnen de gratis tiers. De enige terugkerende kosten zijn AI API calls van minder dan $1 per maand.

De module is het resultaat van 5 audit-rondes, 133 opgeloste issues, 11 database-migraties, en een UAT-testplan met 22 scenario's. Alles is restartable — als er iets misgaat tijdens een sync, pakt de volgende run gewoon waar de vorige stopte.

Dashboard Overzicht

Het dashboard opent op de Reviews-tab. Bovenaan staat de score-hero (je Google-score + projectie), daaronder drie actie-tiles, dan de tabs, en onderaan het Sync & schedule-blok.

Score-hero

Toont je actuele score (bv. 4,8★ · 215 reviews), een progress-bar naar 4,9, hoeveel 5-sterren reviews je nog nodig hebt om van 4,8 naar 4,9 te gaan, en een verwachte datum bij het huidige 5★-tempo (voortschrijdend 12 maanden). "5,0 is niet realistisch" staat er als subtiele noot bij.

Actie-tiles

Tile	Betekenis
⚠ Aandacht	Klikbaar — toont reviews met `needs_attention=true`
💬 Onbeantwoord	Klikbaar — toont reviews zonder eigenaar-antwoord
★ Verdeling	Klikbaar — toont de 5★/4★-telling en opent de Analytics-tab

Sync Runs

De Sync-geschiedenis (uitklapbaar) toont de laatste 10 sync-pogingen met:

Tijdstip — wanneer de sync gestart is
Type — ⏰ Cron (automatisch), 👤 Handmatig, 🔗 Webhook
Status — completed (✅), failed (❌), processing (⏳), skipped (⚠)
Reviews — aantal verwerkte reviews
Error — foutmelding als de sync mislukt is

Schedule

Het Sync & schedule-blok beheert de automatische sync. Om het schema te wijzigen, pauzeer je eerst — pas daarna verschijnen de dropdown en "Toepassen":

Actief — toont het huidige schema als read-only label + knop "Pauzeren"
Gepauzeerd — toont de cron-dropdown + "Toepassen" + "Hervatten"
Nu syncen — handmatige delta-sync (nieuwe reviews ophalen)
Volledig her-scrapen — eenmalige volledige sync (met bevestiging; kost Apify-credits)

Review Tabel

Kolommen

Kolom	Uitleg
Auteur	Naam + avatar van de reviewer. ⚠ badge = aandacht nodig
★	Rating (1-5 sterren)
Tag	AI-gegenereerde categorieën (bv. "eten", "service")
Taal	Originele taal van de review (NL, EN, FR, DE, IT, OTHER)
Vertaling	✓ = vertaald, ⏳ = in queue
Reply	✓ = beantwoord, AI = klik om AI-antwoord te genereren

Filters

Boven de tabel staan vier filters:

🔍 Zoeken — filter op naam of reviewtekst
★ Sterren — filter op specifieke rating
Status — Alle / Onbeantwoord / ⚠ Aandacht / Vertaling pending
Taal — filter op originele taal

Onderaan de tabel staat paginatie (20 reviews per pagina).

Detail Modal

Klik op een rij in de tabel om de detail popup te openen. Deze toont:

Review tekst — de volledige originele review
Taaltabs — schakel tussen origineel en vertalingen (NL, EN, FR, DE)
Eigenaar antwoord — als er al een reply is, wordt deze getoond met datum
Gast in database — zoekt in reservaties of deze persoon bekend is. Toont bezoekhistorie + telefoon
AI Antwoord — genereer een reply in het Nederlands. Editen en kopiëren naar klembord

AI Antwoord Genereren

Voor onbeantwoorde reviews (geen "✓" in de Reply kolom) kan je met één klik een AI-antwoord laten genereren. De AI (DeepSeek) schrijft een oprecht, vriendelijk antwoord van 2-4 zinnen, specifiek afgestemd op de inhoud en toon van de review.

Hoe het werkt

Klik op een review in de tabel → de detail modal opent
Klik op 🤖 AI antwoord onderaan de modal
De AI genereert direct een antwoord. Het tekstvak toont "Antwoord wordt gegenereerd..." — dit duurt 2-4 seconden
Het antwoord verschijnt in een bewerkbaar tekstvak — je kan het aanpassen voordat je het gebruikt
Klik 📋 Kopieer om het antwoord naar je klembord te kopiëren
Plak het antwoord in Google Maps via business.google.com

Wat de AI precies doet

Bij positieve reviews (≥3★): bedankt de gast, benoemt wat gewaardeerd werd, nodigt uit terug te komen
Bij negatieve reviews (<3★): toont oprecht begrip, zonder te vragen om contact op te nemen
Schrijft altijd in de "wij"-vorm (namens het hele NaNoi team)
Spreekt de reviewer aan met "u" (formeel Nederlands)
Gebruikt een warme, persoonlijke toon — geen generieke "Bedankt voor uw review"
Geen aanhef ("Beste ...") en geen afsluiting ("Met vriendelijke groet") — Google Maps toont die zelf

Pro tip: Het antwoord wordt niet opgeslagen in de database. Bij de volgende sync haalt het systeem je antwoord vanzelf op van Google Maps. Zo blijft de database altijd gesynchroniseerd.

Analytics Tab

De Analytics tab geeft je inzicht in de prestaties van het restaurant door de ogen van je gasten. Het is standaard actief bij openen van de pagina.

De vier grafieken

📊 Rating distributie — staafdiagram van 1★ tot 5★ met absolute aantallen. Klik op een staaf om alleen die reviews te zien in de lijst onderaan. Handig om snel alle 3★ reviews te bekijken.
📈 Review volume — hoeveel reviews per maand, over de laatste 12 maanden. Klik op een punt om die maand te filteren. Zo zie je of er in de zomer meer reviews binnenkomen dan in de winter.
📉 Rating trend — gemiddelde score per maand. Daalt de lijn? Dan is er mogelijk iets veranderd in de service of kwaliteit. Stijgt de lijn? Goed bezig!
🏷️ Tags — een cloud van AI-gegenereerde trefwoorden. Klik op een tag om reviews met dat thema te zien. De grootte geeft aan hoe vaak het voorkomt.

Interactieve filtering

Alle grafieken zijn klikbaar. Als je op een element klikt, verandert de Top review sectie onderaan in een lijst met de gefilterde reviews. Je ziet tot 6 reviews per keer. Klik op ← Terug om terug te keren naar de standaardweergave.

Je kan ook op de Aandacht en Onbeantwoord actie-tiles bovenaan klikken — die filteren direct op die categorieën in de Reviews-tab.

Reviews op de Homepage

De reviews die je in het admin dashboard beheert, worden automatisch getoond op de homepage van nanoi.be. Bezoekers zien een carrousel met reviewkaarten die van rechts naar links bewegen. Dit is hoe het werkt.

Wat bezoekers zien

Op de homepage, onder de secties "The Heart of NaNoi" en het menu-overzicht, staat een gouden balk met daarin:

🏆 Review cards — elke card toont de naam van de reviewer, hun Google-sterren (★), en een quote uit hun review. De kaarten schuiven automatisch in een oneindige carrousel
⭐ Google rating — bovenaan de hero-sectie staat de actuele gemiddelde Google-score met het totaal aantal reviews (bijv. "4.8★ · 212 Google Reviews")
🌐 Taal — de getoonde reviewtekst past zich aan aan de taal van de bezoeker. Op /nl ziet men Nederlandse vertalingen, op /de Duitse, op /fr Franse

Welke reviews worden getoond?

Niet alle reviews verschijnen op de homepage. Het systeem selecteert automatisch:

Filter	Waarde	Waarom
Minimale sterren	4★ (instelbaar)	Alleen positieve reviews op de homepage — negatieve reviews beheer je in de admin
Maximaal aantal	6 reviews (instelbaar)	De carrousel toont maximaal 6 kaarten tegelijk voor een strak design
Vertaling vereist	✅ Ja	Alleen reviews waarvan de AI-vertaling klaar is — zo ziet elke bezoeker de juiste taal
Tekst aanwezig	✅ Ja	Alleen reviews mét reviewtekst, geen lege sterren-only reviews

Waar staan deze instellingen?

De minimum sterren en het maximum aantal reviews staan in Instellingen → /admin/settings. In de reviews pagina zie je onder de Analytics tab een Homepage Preview die live laat zien welke reviews er nu op de homepage staan.

Vertalingen op de homepage

Dit is een van de krachtigste features van de module:

Een Franse review van "F C" wordt door AI vertaald naar Nederlands, Engels en Duits
Bezoekers op /nl lezen "Op twee stappen van de Grote Markt...", bezoekers op /de lezen "Zwei Schritte vom Grote Markt..."
Google's eigen vertaling vertaalt de originele review — die is vaak houterig. De NaNoi AI-vertaling leest als een échte restaurantreview in elke taal

Wat gebeurt er bij een nieuwe review?

Google sync (automatisch of handmatig) haalt de nieuwe review op
De review krijgt status translations_status = "pending" — hij verschijnt nog niet op de homepage
De vertalings-queue vertaalt hem (max 10 per run, automatisch)
Zodra translations_status = "done" is, verschijnt de review op de homepage — in de juiste taal per bezoeker

Dit proces is volledig geautomatiseerd. Je hoeft niets te doen.

Tips & Dagelijks Gebruik

Ochtend-routine (2 minuten)

Open /admin → check de health dot op de Reviews module card. Groen = alles ok
Open Reviews → check de actie-tiles: is "Aandacht" > 0? Dan direct actie ondernemen
Check de Sync runs tabel: was de laatste sync succesvol? (✓ completed)

Nieuwe review beantwoorden (1 minuut)

Filter op "Onbeantwoord" in de status-dropdown
Klik de review → detail modal opent
Klik 🤖 AI antwoord → antwoord verschijnt in 3 seconden
Lees het antwoord, pas aan indien nodig, klik 📋 Kopieer
Open business.google.com en plak het antwoord
Optioneel: klik ✅ Afgehandeld om de review als beantwoord te markeren

Negatieve review onderzoeken (3 minuten)

Open de review via de tabel of door op "Aandacht" te klikken
Check "Gast in database" — is dit een bekende gast met eerdere reservaties?
Genereer een AI antwoord met die context en stuur het via Google Maps

Dashboard health dot begrijpen

Op de /admin dashboard pagina zie je een gekleurde indicator op de Reviews module card:

Kleur	Betekenis	Actie
🟢 Groen ✓	Alles gezond — sync recent, geen aandachtspunten	Geen actie nodig
🟡 Oranje !	Aandacht nodig: sync gepauzeerd, of vertalingen in queue, of reviews met needs_attention	Check de reviews pagina voor details
🔴 Rood ✕	Review(s) >48u onbeantwoord — urgente actie nodig	Direct antwoorden op de betreffende review(s)
⚪ Grijs —	Nog nooit gesynced	Start een handmatige sync

Sync Architectuur

De reviews sync werkt via een Cloudflare Worker die Google Reviews ophaalt via Apify en opslaat in Supabase.

Full Sync vs Delta Sync

	Full Sync	Delta Sync
Wanneer	Eenmalig (eerste ingebruikname)	Database bevat reviews
maxReviews	300	20
startDate	Geen	Laatste succesvolle sync-datum
Apify stopt	Na 300 reviews (of eerder als er minder zijn)	Bij review ouder dan startDate
Kosten	~$0.07 (eenmalig)	~$0.006 (per run)

Sync Flow

1. Worker checkt: DB leeg? → Full of Delta
2. Apify scraper start (placeIds=NAOI_PLACE_ID, reviewsOrigin=google, maxReviews + evt. reviewsStartDate)
3. Apify returned reviews → worker filtert op nieuwe `google_id`s
4. Bulk upsert naar Supabase (50 per batch, merge-duplicates) — ALLEEN opslaan
5. Stats bijgewerkt via DB-trigger (`review_stats_trigger`)
6. Vertaling/tags draaien APART via /queue/* — nooit tijdens een Apify-run

Delta Detectie

De worker gebruikt geen Google Places API count-check meer. In plaats daarvan:

Leest alle bestaande google_ids uit Supabase
Vergelijkt met de IDs die Apify teruggeeft
Alleen écht nieuwe reviews worden opgeslagen
reviewsStartDate zorgt dat Apify stopt bij oude reviews → geen onnodige kosten

Deze aanpak is waterdicht — een count-check kan misleidend zijn (bv. +1 nieuwe, -1 oude = zelfde totaal).

Vertaling Queue

Vertalingen gebeuren ontkoppeld van de sync, om DeepSeek- en Apify-kosten te scheiden:

Nieuwe reviews krijgen translations_status = "pending"
/queue/translate pakt maximaal 20 pending reviews per call (begrensde parallellisatie)
DeepSeek vertaalt naar NL, EN, FR, DE — behalve de brontaal (de brontaal blijft het origineel)
Alleen reviews met echte vertalingen worden gemarkeerd als "done"
Na 3 mislukte pogingen → translations_status = "failed" (stopt met retryen; zichtbaar in de admin)
De queue is restartable — volgende run pakt waar de vorige stopte

Realtime Alerts

Het admin dashboard heeft Supabase Realtime subscriptions:

Nieuwe review met needs_attention = true → toast popup
≤1★ review → 🔴 rode "KRITIEKE review" toast
2-3★ review → 🟠 oranje "Nieuwe review" toast
Klik op toast → navigeert naar /admin/reviews

Dashboard Health Dot

Kleur	Betekenis
🔴 Rood ✕	Overdue: reviews >48u onbeantwoord
🟡 Oranje !	Aandacht nodig / auto-sync gepauzeerd / vertalingen in queue
🟢 Groen ✓	Alles OK — sync recent, geen aandachtspunten
⚪ Grijs —	Nog geen sync uitgevoerd

Homepage Carrousel Systeem

De homepage toont reviews via een Astro component (Reviews.astro) die bij elke page load de volgende filters toepast:

is_active = true — alleen actieve reviews
rating >= review_min_stars — default 4★, aanpasbaar in settings
original_text != "" — geen lege reviews
translations_status = "done" — alleen reviews met voltooide AI-vertalingen
order: google_created_at DESC — nieuwste eerst
limit: review_max_display — default 6, aanpasbaar in settings

De vertaling wordt gekozen op basis van de locale in de URL: translations[locale]. Voor /nl wordt translations["nl"] gebruikt, voor /de wordt translations["de"] gebruikt.

De carrousel gebruikt CSS-animatie (reviewSlide) die de kaarten oneindig van rechts naar links laat bewegen. Er worden twee kopieën van de reviews naast elkaar gezet om een naadloze loop te creëren.

GDPR & Data Retention

Verwijderen: Admin kan reviews markeren als "aandacht opgelost". Hard-delete is beschikbaar via de worker API maar niet in de UI.
Avatars: reviewer-foto's worden bewust niet opgeslagen (GDPR). De homepage toont initialen.
Audit trail: Elke delete schrijft een review_sync_logs entry
Retentie: Sync logs ouder dan 90 dagen worden automatisch verwijderd

Architectuur

┌──────────────┐     ┌─────────────────┐     ┌──────────┐
│ Google Maps  │ ←─→ │ Apify Scraper    │ ←─→ │ Worker   │
│ (Reviews)    │     │ (compass~...)    │     │ (CF)     │
└──────────────┘     └─────────────────┘     └────┬─────┘
                                                  │
                    ┌─────────────────────────────┤
                    │                             │
              ┌─────┴─────┐               ┌──────┴──────┐
              │ Supabase   │               │ DeepSeek AI │
              │ (Postgres) │               │ (Vertaling) │
              └───────────┘               └─────────────┘

Worker Endpoints

Method	Path	Auth	Purpose
GET/POST	`/sync?wait=true`	x-api-key	Blocking sync (polling mode)
GET/POST	`/sync`	x-api-key	Async sync (webhook mode)
GET	`/apify/run?runId=X`	x-api-key	Apify run status + recovery (`&ingest=true`)
POST	`/sync?action=delete`	x-api-key	GDPR deletion
POST	`/reply/generate`	x-api-key	AI reply generation
POST	`/reply/mark-responded`	x-api-key	Mark review as responded
GET	`/queue/translate`	x-api-key	Process translation queue (max 20/call)
GET	`/queue/tags`	x-api-key	Process tag queue (max 20/call)
GET	`/logs`	x-api-key	Sync log history
GET	`/status`	x-api-key	Live status + queue depth
POST	`/schedule/pause`	x-api-key	Disable auto-sync
POST	`/schedule/resume`	x-api-key	Enable auto-sync
POST	`/schedule/update`	x-api-key	Update cron schedule

Supabase Schema

reviews

Column	Type	Notes
`id`	UUID PK
`google_id`	TEXT UNIQUE	Apify review ID
`author_name`	TEXT
`rating`	INTEGER	1-5
`original_text`	TEXT	Originele review
`original_lang`	TEXT	nl/en/fr/de/other
`translations`	JSONB	`{nl, en, fr, de}`
`translations_status`	TEXT	pending/done
`tags`	TEXT[]	AI-generated tags
`owner_reply_text`	TEXT	Eigenaar antwoord
`owner_reply_date`	TIMESTAMPTZ
`needs_attention`	BOOLEAN	≤3★ = true
`is_featured`	BOOLEAN	Top review

review_sync_logs

Column	Type
`id`	UUID PK
`run_type`	cron/manual/webhook
`status`	started/processing/completed/failed/skipped
`apify_run_id`	TEXT
`reviews_processed`	INTEGER
`error_message`	TEXT

Subrequest Budget (Free Plan)

Cloudflare Free plan staat 50 subrequests per Worker-invocatie toe. Elke review-vertaling/tag is ~2 subrequests (1 DeepSeek + 1 Supabase PATCH). Daarom:

Ingest (Apify → Supabase): ~7 subrequests voor 215 reviews (1 dataset + 1 getExisting + 5 bulk-batches van 50). Geen avatars → geen ontploffing.
/queue/translate?limit=20: ~41 subrequests (1 select + 20×2) — veilig onder 50.
/queue/tags?limit=20: ~41 subrequests.
Cron: drain 5 vertalingen + 5 tags (~22) + Apify-delta (~6) → ~30, veilig onder 50.

Environment Variables

Variable	Source
`SUPABASE_URL`	wrangler.toml
`SUPABASE_SERVICE_KEY`	Worker secret
`APIFY_API_TOKEN`	Worker secret
`APIFY_ACTOR_ID`	wrangler.toml
`SYNC_API_KEY`	Worker secret
`DEEPSEEK_API_KEY`	Worker secret
`PAGES_DEPLOY_HOOK`	Worker secret
`CF_API_TOKEN`	Worker secret
`CF_ACCOUNT_ID`	wrangler.toml
`WEBHOOK_TOKEN`	Worker secret

Apify Integratie

De worker gebruikt de compass/google-maps-reviews-scraper actor van Apify:

Input: placeIds=[NAOI_PLACE_ID] + reviewsOrigin="google"
Reviews worden gesorteerd op "newest"
Prijs: $0.30 per 1.000 gescrapete reviews
Maandelijkse kost: ~$0.05-$0.15 (binnen $5 free tier)

DeepSeek Prompts

Vertaling Prompt

Vertaler die restaurantrecensies vertaalt naar natuurlijk,
idiomatisch proza (geen "vertaald" gevoel). Vertaal betekenis én
emotie, behoud eigennamen/gerechtnamen, "u"/"vous"/"Sie"-vorm,
verbeter stille schrijffouten, geen gedachtestreepjes of clichés.
Vertaal alleen naar de talen ≠ brontaal. Output = JSON met per
doeltaal één sleutel.

Je bent Jacques, eigenaar van NaNoi Thai Restaurant in Antwerpen.
Schrijf een oprecht, vriendelijk antwoord van 2-4 zinnen.
[<3★: Toon oprecht begrip] [≥3★: Bedank en nodig uit terug te komen]
Gebruik warme toon. Wij-vorm. Spreek aan met "u".
Return ALLEEN het antwoord in het Nederlands.

Troubleshooting

Probleem	Oorzaak	Oplossing
Sync geeft 403	Apify plan verlopen	Hernieuw plan op apify.com → kosteloos via free tier
Geen vertalingen	DeepSeek API key ongeldig	Check `DEEPSEEK_API_KEY` in Cloudflare secrets
Grafieken laden niet	Browser cache oude versie	Hard refresh (Ctrl+Shift+R) of wacht op nieuwe deploy
Health dot grijs	Nog nooit gesynced	Start een handmatige sync (Apify moet actief zijn)
API key foutmelding	Key niet ingesteld in admin	Vul `review_sync_api_key` in via /admin/reviews Sync API Key veld
Schedule pauze werkt niet	CF_API_TOKEN mist scope	Token moet Workers Scripts:Edit permissie hebben
"Too many subrequests"	Free plan limiet (50)	Batch sizes verkleinen of upgraden naar paid plan