# Architettura

## Obiettivo

Il workspace consolida una suite hospitality unica attorno a moduli esistenti e moduli nativi nuovi, senza riscrivere a caso le due legacy principali:

- `PRENOTAZIONI_IA`
- `MENU2.0`

L'architettura reale oggi e' gia operativa su quattro assi:

- portale centrale
- backend condiviso
- modulo ordini nativo
- integrazione progressiva delle legacy con auth, tenancy e prompt tenant-aware

## Struttura del repository

```text
.
├── AGENT.md
├── MENU2.0
├── PRENOTAZIONI_IA
├── apps
│   ├── backend-hub
│   ├── homemade
│   ├── menu-legacy
│   ├── ordini
│   ├── portal
│   ├── prenotazioni-legacy
│   └── reverse-proxy
├── docs
├── packages
│   ├── auth
│   ├── billing
│   ├── config
│   ├── llm
│   ├── shared
│   ├── tenancy
│   ├── types
│   └── ui
├── scripts
├── docker-compose.yml
└── .env.example
```

## Ruolo dei componenti

### `apps/portal`

Hub UI principale di `powerup.cool`.

Stack:

- React 18
- Vite
- React Router

Responsabilita attuali:

- pagina di accesso e registrazione locale
- recupero della sessione reale
- Home operativa con assistente del locale
- dashboard moduli
- pagina `Documenti` per Google Workspace
- launcher moduli con propagazione della sessione

Route principali:

- `/`
- `/login`
- `/home`
- `/dashboard`
- `/documents`
- `/architecture`
- `/modules/:moduleKey`

Nota importante:

- la vecchia idea di una pagina globale `/settings` non rappresenta piu lo stato reale del portale

### `apps/backend-hub`

Backend FastAPI centrale della piattaforma.

Non e piu solo uno scaffold. Oggi gestisce davvero:

- auth e registrazione del locale
- registry SQLite di tenant, venue, utenti, moduli e sessioni
- risoluzione del contesto tenant
- configurazioni AI tenant-aware
- prompt e asset del modulo menu
- Home assistant grounded su dati reali
- integrazione Google Workspace
- endpoint di stato dei moduli

Persistenza principale:

- registry: `/data/platform_registry.sqlite3`
- database tenant: `/data/tenants/<tenant-slug>.sqlite3`
- asset menu: `/data/menu-assets`

### `apps/ordini`

Modulo nativo della piattaforma.

Architettura:

- frontend statico HTML/CSS/JS servito da Nginx
- backend FastAPI + SQLAlchemy

Persistenza reale:

- tenant autenticato dal portale -> database SQLite dedicato del locale
- fallback legacy standalone -> `ORDINI_DATABASE_URL` PostgreSQL

Il modulo entra direttamente dal portale tramite query `?session=...` oppure tramite login manuale fallback.

### `PRENOTAZIONI_IA`

Legacy prenotazioni preservata.

Stato attuale:

- frontend Next.js 14
- backend FastAPI + SQLAlchemy
- database PostgreSQL
- venue corrente risolta dal contesto del portale
- impostazioni prenotazioni e WhatsApp separate per venue

Non va trattata come modulo da rifattorizzare liberamente.

### `MENU2.0`

Legacy menu preservata.

Stato attuale:

- frontend statico HTML/CSS/JS
- resta apribile standalone
- dal portale riceve sessione e riferimento API per mostrare la configurazione tenant
- il prompt tenant del menu viene composto nel `backend-hub`

### Wrapper `apps/prenotazioni-legacy` e `apps/menu-legacy`

Queste cartelle non contengono la business logic delle legacy.

Servono a:

- containerizzare le legacy nel compose root
- documentare il loro perimetro di integrazione
- evitare di mescolare wrapper e sorgente originale

### `packages/*`

Layer shared del workspace.

Uso reale oggi:

- `packages/types` -> tipi TypeScript condivisi
- `packages/config` -> catalogo moduli e metadati statici
- `packages/shared` -> helper neutri
- `packages/llm` -> helper URL/config LLM

Stato placeholder:

- `packages/auth`
- `packages/billing`
- `packages/tenancy`
- `packages/ui`

La logica reale di auth e tenancy vive ancora in `apps/backend-hub`, non in questi package.

## Auth, sessioni e tenancy

Flusso attuale:

1. registrazione da `portal`
2. creazione tenant, venue, utente admin e moduli nel `backend-hub`
3. creazione del database SQLite dedicato del locale
4. salvataggio sessione reale nel client
5. apertura dei moduli con token del gestionale

Dettagli pratici:

- `portal` usa `Authorization: Bearer <token>` verso `backend-hub`
- `ordini` riusa lo stesso token e apre il database del tenant
- `PRENOTAZIONI_IA` sincronizza il locale corrente tramite `backend-hub /tenants/context`
- le sessioni sono persistenti e non dipendono piu da `tenantContext` mock nel frontend

## Assistente operativo e LLM

La Home del portale e un assistente grounded, non una chat generica.

Oggi puo:

- leggere ordini, storico, prodotti, prenotazioni, note e obiettivi
- scrivere prenotazioni, note, obiettivi e ordini sospesi
- creare Google Docs e Google Sheets quando Workspace e collegato

Il comportamento e ibrido:

- filtri deterministici per le richieste chiare e rischiose
- tool reali per lettura e scrittura sui dati
- LLM come layer di pianificazione o sintesi

Il servizio LLM resta esterno al repository ed e configurato via:

```env
LLM_BASE_URL=http://amicifede.ddns.net:1234/v1
```

## Routing reale

Topologia di produzione documentata in `AGENT.md`:

- Apache su `*:443`
- `/` -> `portal`
- `/api/` -> `backend-hub`
- `/prenotazioni` e `/prenotazioni/` -> frontend prenotazioni
- `/prenotazioni-api/` -> backend prenotazioni
- `/menu/` -> menu legacy
- `/ordini/` -> modulo ordini corretto lato prodotto

Nota importante su `ordini`:

- Apache inoltra `/` al `portal`
- il `portal` Nginx gestisce internamente `/ordini/`
- `ordini-frontend` proxya `/api/` verso `ordini-backend`

Quindi l'URL prodotto corretto e:

- `https://powerup.cool/ordini/`

## Principi di evoluzione

I principi attuali del repository sono:

- preservare le legacy finche non esiste un motivo concreto per toccarle
- spostare nel `backend-hub` solo cio che porta davvero valore condiviso
- mantenere i moduli nuovi coerenti con la UX di `powerup.cool`
- evitare configurazioni sensibili hardcodate nel frontend