Genomen Beslissingen

Architecture Decision Records (ADRs) — een overzicht van alle bewuste keuzes die zijn gemaakt tijdens de planningsfase, inclusief de overwegingen.

ADR-001: Sentoo als primaire betaaloplossing

Datum: Planning fase Status: Besloten

Beslissing: Sentoo wordt gebruikt als primaire betaaloplossing voor lokale klanten op Aruba.

Overwegingen:

Stripe niet beschikbaar voor Arubaanse NV (Caribisch eiland, geen supported country)
Verifone/2Checkout ondersteunt Caribbean maar kost ~5,5% per transactie (inclusief cross-border fee)
Sentoo kost 1% met een maximum van AWG/USD 1,50 — significant goedkoper
Sentoo integreert direct met Aruba Bank, CMB en Banco di Caribe — de banken die de doelgroep gebruikt
Sentoo heeft een REST API met webhooks voor automatische statusupdates
~90% van de klanten heeft een lokale bankrekening

ADR-002: Geen extern facturatiesysteem (Zoho Invoice afgewezen)

Datum: Planning fase Status: Besloten

Beslissing: Factuurlogica wordt volledig in de app gebouwd. Geen extern facturatiesysteem zoals Zoho Invoice.

Overwegingen:

Alle boekingsdata en klantdata leven al in de eigen app
Een factuur genereren vanuit bestaande data is technisch eenvoudig
Zoho Invoice voegt complexiteit toe (extra API integratie, extra kosten, extra afhankelijkheid)
Sentoo werkt als standalone betaaloplossing zonder facturatiesysteem
Voor een hondenhotel met beperkt volume is Zoho overkill

ADR-003: Supabase als data platform

Datum: Planning fase Status: Besloten

Beslissing: Supabase wordt gebruikt voor database, auth en storage. Server-side API logica draait op Hono (niet Supabase Edge Functions).

Overwegingen:

Supabase biedt PostgreSQL, Auth, Storage en pg_cron in één platform
Row Level Security zorgt voor veilige data-isolatie per gebruiker
pg_cron voor maandelijkse abonnementsfacturering zonder externe scheduler
API logica op Hono (CF Workers) in plaats van Edge Functions voor meer controle over routing en middleware

ADR-004: Cloudflare Pages + Workers voor hosting

Datum: Planning fase Status: Besloten

Beslissing: De app draait op Cloudflare Pages (Vite SPA), de API op Cloudflare Workers (Hono), docs op Cloudflare Pages (Starlight).

Overwegingen:

Gratis tier ruim voldoende voor de initiële fase
Workers: 100K requests/dag gratis, lage latency op de edge
Globale CDN met goede Caribbean dekking
Automatisch SSL zonder configuratie
Alles op Cloudflare — geen Vercel of andere hosting nodig

ADR-005: Resend voor email

Datum: Planning fase Status: Besloten

Beslissing: Resend wordt gebruikt voor alle transactionele emails.

Overwegingen:

Developer-vriendelijke API met React Email ondersteuning
Goede deliverability
Betaalbaar bij kleine volumes (gratis tot 3.000 emails/maand)
Ondersteunt aangepast domein voor professionele uitstraling

ADR-006: Vier talen inclusief Papiamento in v1.0

Datum: Planning fase Status: Besloten

Beslissing: De app ondersteunt NL, EN, ES en Papiamento vanaf versie 1.0.

Overwegingen:

Papiamento is de moedertaal van de meeste lokale Arubanen
Weglaten van Papiamento zou de lokale gebruikerservaring schaden
Vertalingen worden aangeleverd door de opdrachtgever — geen technische blokkade
App wordt i18n-ready gebouwd vanaf dag één om retrofitting te vermijden

ADR-007: Geen automatische incasso voor unlimited abonnement

Datum: Planning fase Status: Besloten

Beslissing: Het unlimited abonnement werkt via maandelijkse betaallinks (Sentoo), niet via automatische incasso.

Overwegingen:

Sentoo vereist altijd actieve autorisatie van de klant — echte “stille” incasso is niet mogelijk
Automatische incasso via lokale bank vereist een aparte machtiging en bancaire afspraken
Betaallink via WhatsApp/email is op Aruba een gangbare en geaccepteerde manier van factureren
Implementatie is eenvoudiger en vereist geen extra bankafspraken

ADR-008: Geen aparte publieke website

Datum: Maart 2026 Status: Besloten

Beslissing: Er komt voorlopig geen aparte publieke website. De app bestaat uit het bookingsformulier (klantportaal) en admin panel als Vite SPA.

Overwegingen:

Het hondenhotel heeft geen behoefte aan een marketing/landing page
Klanten komen direct naar het bookingsformulier
Één app (Vite SPA) met role-based access voor klanten en admin
Minder complexiteit in de monorepo (geen Astro public-site app)

ADR-009: Vite + React 19 + Zustand als frontend stack

Datum: Maart 2026 Status: Besloten

Beslissing: De frontend app wordt gebouwd met Vite 6, React 19, Zustand 5, Tailwind CSS en react-i18next.

Overwegingen:

Vite HMR < 50ms, snellere development dan Next.js
SPA-model past bij een ingelogde applicatie waar SSR geen meerwaarde biedt
Zustand: minimale state management, framework-agnostisch
Tailwind: utility-first CSS, snelle prototyping
react-i18next: proven library voor meertalige React apps

ADR-010: pnpm monorepo met Hono API

Datum: Maart 2026 Status: Besloten

Beslissing: Het project wordt een pnpm monorepo met apps/web (Vite SPA), apps/api (Hono op CF Workers), apps/docs (Starlight) en packages/shared.

Overwegingen:

Gedeelde types en utilities via packages/shared
Hono op CF Workers voor de API: type-safe, lichtgewicht, edge deployment
Aparte API-laag scheidt business logic van frontend
Eén repo, consistente tooling, eenvoudiger dependency management

ADR-011: Alle diensten in scope v1.0

Datum: Maart 2026 Status: Besloten

Beslissing: Alle diensten uit het systeemoverzicht worden gebouwd in v1.0: testdag, daycare (drop-in + Paw Vouchers + unlimited), boarding met 4 kamertypes, training (2 pakketten) en bath & brush.

Overwegingen:

Het systeemoverzicht van de opdrachtgever beschrijft alle diensten als kernfunctionaliteit
Strippenkaarten, unlimited en trainingen stonden eerder op “v1.1” maar zijn essentieel voor de dagelijkse operatie
Boarding met kamertypes en kortingsregels is de primaire inkomstenbron
De testdag is verplicht voor nieuwe klanten — zonder dit werkt het aanmeldproces niet
Alle prijzen en regels zijn nu concreet bepaald

ADR-012: Eigen facturatie (geen Invoice2go)

Datum: Maart 2026 Status: Besloten

Beslissing: Invoice2go wordt volledig vervangen door eigen factuurlogica in de app. Facturen worden gegenereerd, als PDF opgeslagen en betaallinks via Sentoo verstuurd.

Overwegingen:

Alle data (boekingen, klanten, prijzen) leeft al in de eigen app
Concept-factuur flow vereist voor langdurig verblijf met handmatige korting
Invoice2go voegt onnodige complexiteit en kosten toe
Sentoo is de betaalprovider, geen aparte facturatietool nodig

ADR-013: Tanstack Query, shadcn/ui en React Email

Datum: Maart 2026 Status: Besloten

Beslissing: Tanstack Query vervangt SWR voor data fetching. shadcn/ui wordt de UI component library. React Email wordt gebruikt voor email-templates en factuur-templates.

Overwegingen:

Tanstack Query i.p.v. SWR: betere mutation support met optimistic updates (belangrijk voor boekingsflow), ingebouwde devtools, actiever in development. SWR is prima voor read-heavy apps, maar Dog Hotel heeft veel CRUD-operaties
shadcn/ui: copy-paste componenten op Tailwind (forms, tables, dialogs, calendars, date pickers). Geen externe dependency, vol eigenaarschap. Past bij admin panel + klantportaal met veel formulieren
React Email: React componenten voor email templates. Integreert naadloos met Resend

ADR-014: Custom facturatie met Forme PDF

Datum: Maart 2026 Status: Besloten

Beslissing: Facturatie wordt custom gebouwd in de Hono API. PDF rendering via Forme PDF (Rust/WASM engine op Cloudflare Workers). Geen extern billing platform.

Overwegingen:

Waarom custom logica: Sentoo wordt niet ondersteund door standaard billing tools (Lago, UniBee). De concept-factuur flow (genereer → personeel past aan → definitief) en domein-specifieke kortingsregels (20% multi-hond, staffel langdurig) vereisen maatwerk
Waarom geen Lago/UniBee: overkill voor een hondenhotel, extra infrastructuur, geen Sentoo integratie, moeilijk te combineren met concept-factuur flow
Waarom Forme PDF: native Hono integratie (@formepdf/hono @formepdf/react), Rust/WASM engine (~3MB) draait direct op CF Workers zonder headless browser, rendering in milliseconden, React-based templates
Waarom niet @react-pdf/renderer: WASM compatibility issues op Cloudflare Workers (yoga-layout)
Waarom niet pdfmake: werkt op Workers maar minder ergonomische DX dan React templates
API structuur: POST /api/invoices (custom logica) → POST /api/invoices/:id/pdf (Forme PDF) → POST /api/invoices/:id/send (Sentoo + Resend)

ADR-015: React Hook Form, date-fns en Sentry

Datum: Maart 2026 Status: Besloten

Beslissing: React Hook Form + Zod voor formulieren, date-fns voor datumlogica, Sentry voor error monitoring.

Overwegingen:

React Hook Form: de facto standaard, shadcn/ui is erop gebouwd, Zod resolver voor gedeelde validatie met API. Essentieel voor onboarding (3 stappen) en boekingsflow (5 stappen). Formik is verouderd, Tanstack Form nog te jong
date-fns: tree-shakeable (~2KB per functie), NL/EN/ES locales ingebouwd, werkt met native Date objecten. Nodig voor openingstijden validatie, boarding dagentelling, vaccinatie-expiry, factuurdata. dayjs niet tree-shakeable, luxon te groot
Sentry: error monitoring voor een app die betalingen verwerkt. Gratis tier 5K events/maand. Als een Sentoo webhook faalt of factuur niet genereert, moet je dat direct weten

ADR-016: Sentoo integratie details (uit publieke docs)

Datum: Maart 2026 Status: Vastgesteld (volledig na onboarding)

Vastgesteld op basis van Sentoo publieke documentatie en FAQ:

Sandbox: Sentoo biedt een integration environment voor testen. Developers krijgen bij onboarding: merchant key, REST API docs, OpenAPI v3/Swagger en toegang tot de sandbox
Cards (Visa/Mastercard): beschikbaar als apart product. Kosten: gateway fee $0.27–$0.48 + card processing 0.25–0.75% + MDR bank + $20/maand + eenmalige setup fee. 3D Secure en PCI DSS ingebouwd
Banken: 7 banken ondersteund — Aruba Bank, Banco di Caribe, CMB, MCB Bonaire, MCB Curaçao, Orco Bank, WIB
API authenticatie: secret key per merchant, periodiek te roteren
Rate limits: niet gedocumenteerd, waarschijnlijk geen harde limiet voor normale volumes
Talen betaalpagina: alleen Engels in publieke docs. Papiamento en taalparameter navragen bij onboarding
Webhook formaat: niet in publieke docs, API docs achter login op developer.sentoo.io

ADR-017: CSV export voor boekhouder

Datum: Maart 2026 Status: Besloten

Beslissing: CSV export wordt gebouwd in het admin panel onder /admin/invoices. De boekhouder kan facturen exporteren met filters (periode, status).

ADR-018: Papiamento vertalingen

Datum: Maart 2026 Status: Besloten

Beslissing: Dog Hotel Aruba levert alle Papiamento vertalingen aan en reviewt op correctheid. Inclusief maand- en dagnamen. Het development team bouwt de i18n-infrastructuur (react-i18next met namespace-based JSON), de opdrachtgever vult de vertaalbestanden.

ADR-019: GitHub Actions notificaties via Resend

Datum: Maart 2026 Status: Besloten

Beslissing: Deploy notificaties worden verstuurd via email (Resend). Geen extra integratie nodig — Resend zit al in de stack.

ADR-020: Audit log als optionele feature

Datum: Maart 2026 Status: Besloten

Beslissing: Audit log wordt gebouwd als optionele feature in v1.0 (standaard uit, activeerbaar in admin settings). Registreert wie wat wanneer heeft gedaan in het admin panel.

Overwegingen:

Tabel audit_logs met user_id, action, entity_type, entity_id, metadata, created_at
Automatisch loggen bij: betaling markeren, boeking annuleren, prijzen wijzigen, klantdata bewerken
Inzichtelijk via /admin/settings/audit-log
Standaard uit — geen overhead als het niet nodig is
Waardevol zodra >1 medewerker actief is

ADR-021: Annuleringsbeleid (uit algemene voorwaarden)

Datum: Maart 2026 Status: Besloten

Beslissing: 50% deposit is niet-restitueerbaar onder alle omstandigheden. Geen cash restitutie. Reservering vervalt automatisch na 7 dagen zonder betaling. Geldt voor alle diensten.

Bron: Algemene voorwaarden Dog Hotel Aruba (rules.txt + factuur PDF)

ADR-022: Minimumleeftijd en toelatingsregels

Datum: Maart 2026 Status: Besloten

Beslissing: Honden onder 6 maanden worden niet toegelaten. Vaccinaties minimaal 7 dagen voor check-in, niet ouder dan 12 maanden. Vlooien/wormbehandeling binnen 30 dagen voor check-in. Zwangere/loopse honden niet toegelaten.

Bron: Algemene voorwaarden Dog Hotel Aruba, punt 3, 4, 7, 12

ADR-023: Aansprakelijkheidsverklaring (waiver)

Datum: Maart 2026 Status: Besloten

Beslissing: Klanten moeten bij registratie de volledige algemene voorwaarden (25 punten) digitaal accepteren. Dit omvat aansprakelijkheidsvrijwaring, foto/video toestemming, medicatiebeleid, en abandonmentclausule.

Overwegingen:

De huidige algemene voorwaarden bevatten 25 clausules die juridisch bindend zijn
Digitale acceptatie (checkbox + timestamp) vervangt het papieren formulier
Voorwaarden worden per taal opgeslagen en zijn bewerkbaar door admin
Versiegeschiedenis wordt bijgehouden

ADR-024: Arubaanse belastingen (BBO + BAZV)

Datum: Maart 2026 Status: Besloten

Beslissing: Alle facturen bevatten BBO (6%) en BAZV (1.5%) inbegrepen in het totaalbedrag. Creditcard betalingen krijgen een toeslag van 5%.

Bron: Voorbeeldfactuur Dog Hotel Aruba (Invoice2go)

ADR-025: Kamertoewijzing per hond

Datum: Maart 2026 Status: Besloten

Beslissing: Het systeem houdt per hond bij in welke specifieke kamer deze verblijft, inclusief de periode (van-tot). Kamertoewijzing is kernfunctionaliteit, niet een toekomstige uitbreiding.

Overwegingen:

Het hotel wil weten welke hond in welke kamer zit (bijv. i.v.m. airco, schoonmaak, bezetting)
Nieuwe tabel room_assignments koppelt een hond aan een specifieke kamer per boeking
Dashboard toont per kamer welke hond erin zit en tot wanneer
Maakt het mogelijk om kamers te blokkeren voor schoonmaak of onderhoud

Bron: Antwoorden opdrachtgever (maart 2026)

ADR-026: Bijzonderheden per hond in plaats van incidentregistratie

Datum: Maart 2026 Status: Besloten

Beslissing: Er komt geen formeel incidentregistratiesysteem. In plaats daarvan krijgt elke hond een special_notes veld voor bijzonderheden die bij een volgend bezoek relevant zijn. Bij incidenten (ziekte, verwonding) wordt direct contact opgenomen met de eigenaar.

Overwegingen:

Incidentregistratie met foto’s en formulieren is overbodig voor de huidige werkwijze
Het hotel neemt bij incidenten telefonisch contact op met de eigenaar
Een vrij tekstveld per hond is voldoende om bijzonderheden vast te leggen voor volgende bezoeken
Het bestaande notes veld op de dogs tabel is voor interne admin-notities; special_notes is specifiek voor terugkerende bijzonderheden

Bron: Antwoorden opdrachtgever (maart 2026)

ADR-027: Volledig vooraf betalen, geen extra borg

Datum: Maart 2026 Status: Besloten

Beslissing: Alles moet vooraf betaald worden: 50% bij het boeken en de resterende 50% vóór of bij check-in. Er is geen aparte borg of deposit, ongeacht kamertype of verblijfsduur.

Overwegingen:

Eenvoudiger betalingsflow: twee betalingsmomenten, geen retourlogica
Geen extra complexiteit voor borgbeheer of terugbetalingen
Consistent beleid voor alle kamertypes en verblijfsduren
De 50% aanbetaling is niet-restitueerbaar (zie ADR-021)

Bron: Antwoorden opdrachtgever (maart 2026)

ADR-028: Retentiebeleid documenten

Datum: Maart 2026 Status: Besloten

Beslissing: Facturen worden minimaal 5 jaar bewaard (wettelijke verplichting Aruba). Vaccinatiebewijzen (documenten) hoeven niet permanent opgeslagen te blijven, maar de vervaldatum (expiry_date) wordt wel bewaard zodat het systeem kan berekenen tot wanneer een vaccinatie geldig is en klanten tijdig kan herinneren.

Overwegingen:

Facturen: 5 jaar bewaarplicht conform Arubaanse wetgeving
Facturen en bijbehorende data worden nooit automatisch verwijderd
Bij accountverwijdering blijven factuurrecords en PDFs bewaard tot de wettelijke termijn is verlopen
Vaccinatiedocumenten: geen wettelijke bewaarplicht, maar expiry-datum is operationeel belangrijk
Het systeem stuurt automatisch herinneringen wanneer een vaccinatie bijna verloopt
Klanten kunnen een nieuw vaccinatiebewijs uploaden wanneer nodig; het oude document kan worden overschreven

Bron: Antwoorden opdrachtgever (maart 2026)

ADR-029: Algemene voorwaarden verplicht, geen privacyverklaring

Datum: Maart 2026 Status: Besloten

Beslissing: Er komt geen privacyverklaring op de app. Wel moeten klanten akkoord gaan met de algemene voorwaarden wanneer zij hun hond bij het hotel brengen. Dit is al onderdeel van de registratieflow (ADR-023).

Overwegingen:

Privacyverklaring is op Aruba niet wettelijk verplicht voor dit type bedrijf
De bestaande algemene voorwaarden (25 punten) dekken aansprakelijkheid, foto/video toestemming en overige relevante zaken
Klanten accepteren de voorwaarden digitaal bij registratie (checkbox + timestamp)
Voorwaarden zijn bewerkbaar per taal met versiegeschiedenis

Bron: Antwoorden opdrachtgever (maart 2026)