Architettura di Fooodo
Come è costruito Fooodo — la suddivisione in due servizi tra app menu e servizio di pagamento, il modello multi-tenancy azienda/ristorante/tavolo, il contratto di connettore POS-agnostico e dove si colloca UVS.
Fooodo funziona come due servizi cooperanti più un POS esterno, raggiunto tramite un contratto di connettore POS-agnostico. Questa pagina è la mappa del sistema: come i componenti si collegano, perché sono separati e come funziona il multi-tenancy.
I due servizi
- App menu. Flusso rivolto al cliente (QR → sfoglia → ordina), il pannello di amministrazione per l'operatore e tutto il traffico del connettore POS.
- Servizio di pagamento. Servizio separato dietro un'API autenticata tramite token. Gestisce l'integrazione con Mollie, il routing dei webhook, il routing delle donazioni e il routing delle mance. Dispone di un proprio pannello di amministrazione interno.
- Connettore POS. Qualunque POS utilizzi il ristorante. Fooodo lo tratta come sistema di riferimento per il menu e come fonte di verità della cucina per gli ordini. R-Keeper è il connettore di riferimento attivo oggi; gli altri connettori POS sono definiti per singolo cliente — il contratto del connettore stesso è POS-agnostico.
I due servizi Fooodo comunicano tramite un'API HTTP autenticata; non condividono database, code né deployment. Possono essere distribuiti in modo indipendente.
Perché separare il servizio di pagamento
Tre motivi:
- Il perimetro di conformità rimane ridotto. I dati della carta toccano esclusivamente il servizio di pagamento; l'app menu riceve un URL di checkout e un callback. Il perimetro PCI è circoscritto a un'unica codebase.
- Il servizio di pagamento è riutilizzabile. È stato progettato per servire nel tempo più superfici Fooodo, non solo l'app menu attuale. I nuovi prodotti lo utilizzano senza dover reimplementare la logica di pagamento.
- Isolamento dei guasti. Se Mollie subisce un'interruzione regionale, l'app menu rimane operativa; gli ordini si accodano nello stato "pronti per il pagamento" e vengono riconciliati quando il servizio di pagamento si ripristina.
Multi-tenancy
Ogni record nell'app menu è circoscritto attraverso questa gerarchia:
- Companytenant boundary · brand · billing
- RestaurantPOS config · hours · default flow
- TableQR code · per-table flow override
- Orderitems · payments · tips · donations
- Company è il confine del tenant. Attualmente è presente un'unica azienda attiva in produzione (Čili Pizza), ma la separazione dei tenant è applicata ovunque — aggiungere una seconda catena non richiede un deployment separato.
- Gli amministratori di ristorante possono gestire solo il proprio ristorante — il sistema dei ruoli lo impone a livello di policy.
- Ogni QR code si risolve in un tavolo specifico di un ristorante specifico. Non esiste un codice "scansiona per ordinare" condiviso; Fooodo sa sempre a quale posto è destinato un ordine. Questo è ciò che rende possibili il pagamento differito (Pay-Later), la divisione del conto al tavolo e le analitiche per posto.
Dove si colloca UVS
UVS è il nucleo degli ordini e delle operazioni all'interno dell'app menu — il flusso di eventi centrale che registra tutto ciò che la piattaforma scrive (ordini, pagamenti, stato dei tavoli, ticket di cucina) prima di propagarlo ai consumer (il connettore POS attivo, il servizio di pagamento, i moduli futuri).
Per gli integratori questo ha un impatto concreto: i moduli non comunicano direttamente tra loro, e il contratto è POS-agnostico. Un connettore per un nuovo POS non tocca il flusso della cucina né il servizio di pagamento — parla il contratto UVS e ottiene gratuitamente pagamenti, multi-tenancy e reportistica. R-Keeper è un'implementazione di quel contratto; il contratto stesso è il sistema. Il contratto è documentato nel repository di integrazione, che i partner ricevono durante l'onboarding.
Stack in sintesi
| Componente | Forma |
|---|---|
| App menu | Backend PHP, frontend React, PostgreSQL, coda di job basata su Redis |
| Servizio di pagamento | Servizio PHP indipendente con proprio database e pannello di amministrazione |
| Provider di pagamento | Mollie (Carta, Apple Pay, Google Pay) |
| Connettore POS | R-Keeper (attivo); altri connettori POS definiti per singolo cliente |
| Sito marketing | Next.js + next-intl + Fumadocs (questo sito) |
Le versioni specifiche dei framework sono intenzionalmente omesse da questa superficie pubblica — i partner che sviluppano connettori POS ricevono il pinning delle versioni durante l'onboarding insieme al repository di integrazione.
Cosa si trova dove
- Gestione menu, ordini, tavoli, flusso rivolto al cliente → app menu.
- Dati della carta, rimborsi, metodi di pagamento, mance, donazioni → servizio di pagamento.
- Fonte di verità del menu, ticket di cucina, report → il tuo POS (R-Keeper oggi, altri connettori man mano che vengono rilasciati).
- Testi marketing, documentazione pubblica, assistente AI, server MCP → questo sito.
Se stai integrando con Fooodo, la superficie API che ti interessa è l'API esterna dell'app menu. Il servizio di pagamento è interno — l'app menu funge da proxy verso di esso.
Iniziare con Fooodo
Il percorso di onboarding pratico da "abbiamo appena firmato" agli ordini live nella prima sede — sincronizzazione del menu, tavoli QR, la prova generale e cosa monitorare nella prima settimana.
Flussi degli ordini — Pay-First vs Pay-Later
Quando utilizzare Pay-First o Pay-Later, come si comporta ciascuno dall'inizio alla fine, gli stati degli ordini che gli operatori vedono nell'admin e i job in background che mantengono gli ordini sincronizzati con il POS.