ARCHITECTURE.md

Editor⌘S per salvare

# ARCHITECTURE.md — Mappa Architetturale Completa

**Scopo:** Questo file è la fonte di verità per TUTTE le scelte architetturali del sistema.
**Regola:** Prima di QUALSIASI modifica infrastrutturale, leggi questo file. Se la modifica contraddice una decisione documentata qui, FERMATI e chiedi.

---

## 1. Principi Architetturali

- **Cloudflare come piattaforma unica** per DNS, domini, hosting, tunnel, Pages
- **Niente duplicazioni** — un servizio per ogni funzione, non due
- **SQLite come source of truth** per i task (tasks.db), tasks.json è solo export
- **WhatsApp come canale principale** per Lorenzo (Telegram spesso non lo vede)
- **Solo Asia modifica infrastruttura** — gli altri agenti non toccano config/architettura
- **Acquisti passano da Asia** — carta del team nel suo workspace, budget autonomo < €100

---

## 2. Domini e DNS

### lorenzopinto.it
- **Registrar:** Register.it (login: `LP43214-EURO`) — NON si tocca più, tutto si gestisce da Cloudflare
- **NS:** `jobs.ns.cloudflare.com`, `rafe.ns.cloudflare.com` (cambiati 2026-03-09)
- **Zona Cloudflare:** `ec676bad49549cbaaad39f96fa4ede8a` (status: pending → active dopo propagazione NS, 24-48h)
- **DNS puliti il 2026-03-09:** rimossi tutti i record vecchi Register.it (A, AAAA, MX, SRV, SPF)

**Struttura sottodomini:**
```
lorenzopinto.it                    → vuoto (nessun record A, da decidere in futuro)
app.lorenzopinto.it                → Hub Progetti (Cloudflare Pages: app-hub)
dashboard.app.lorenzopinto.it      → Agent Dashboard (tunnel Cloudflare)
sit.app.lorenzopinto.it            → Students in Town (Cloudflare Pages: students-in-town)
```

**Pattern:** tutte le app vanno sotto `*.app.lorenzopinto.it`, con `app.lorenzopinto.it` come hub/indice.

**Record DNS attuali:**
| Nome | Tipo | Destinazione |
|------|------|-------------|
| app | CNAME | app-hub-8at.pages.dev (Pages) |
| dashboard.app | CNAME | fd7e2b13-...cfargotunnel.com (tunnel) |
| sit.app | CNAME | students-in-town.pages.dev (Pages) |
| @ | TXT | google-site-verification (mantenuto) |

**Cloudflare Pages projects:**
| Progetto | URL Pages | Custom domain |
|----------|-----------|---------------|
| app-hub | app-hub-8at.pages.dev | app.lorenzopinto.it |
| students-in-town | students-in-town.pages.dev | sit.app.lorenzopinto.it, studentsintown.com |

**Tunnel:** `mac-mini` / `fd7e2b13-dfa7-422f-86c7-7406568e19cd`
  - Config: `~/.cloudflared/config.yml`
  - Ingress: `dashboard.app.lorenzopinto.it` → `http://localhost:3000`
  - ⚠️ Creato su account vecchio Lorenzo — verificare cross-account dopo propagazione NS

### studentsintown.com
- **Registrar:** Cloudflare Registrar (account Voltaasia)
- **Zona Cloudflare:** `3b4b8ed9232ca62d76c9bbba13a5cfdd` (status: active)
- **Hosting:** Cloudflare Pages, progetto `students-in-town`
- **DNS:**
  - `studentsintown.com` → CNAME → `students-in-town.pages.dev` (proxied)
  - `www.studentsintown.com` → CNAME → `students-in-town.pages.dev` (proxied)
- **Deploy:** `wrangler pages deploy out/ --project-name students-in-town`
- **Scadenza dominio:** 9 marzo 2027, auto-rinnovo attivo
- **Costo:** $10.46/anno
- **Progetto locale:** `~/.openclaw/projects/students-in-town-web/`
- **Stack:** Next.js + Tailwind CSS, export statico (`next build` → `out/`)

### studentsintown.it
- **Non registrato.** Cloudflare Registrar non supporta .it
- **Decisione:** rimandata post-MVP. Se serve, usare Register.it o Aruba.

---

## 3. Cloudflare

### Account
- **Account attivo (Voltaasia):** `bd4a9927815d17a941acc736bd6c2b1c` — email: voltaasia@gmail.com
- **Account vecchio (Lorenzo):** `9a22114a9e50dae583fe8feca63977cf` — INACCESSIBILE (CAPTCHA bloccante)

### API Tokens
| Nome | Token | Permessi | Scope |
|------|-------|----------|-------|
| DNS Edit | `esIRWcs5ktFFRYHOYzPoQLJ6ZgijbJBuPNWBF6YL` | Zone DNS Edit | Tutte le zone |
| Pages Deploy | `hgI0HA2U0UHFUSFslDvOprdtx_SvGk9CmQBlh6y5` | Pages Read + Write | Account Voltaasia |

### Servizi in uso
- **Cloudflare Registrar** — studentsintown.com
- **Cloudflare DNS** — zone per lorenzopinto.it e studentsintown.com
- **Cloudflare Pages** — hosting Students in Town
- **Cloudflare Tunnel** — accesso dashboard agent (tramite account vecchio)

---

## 4. Team Multi-Agent (OpenClaw)

### Agenti
| ID | Nome | Ruolo | Model | Workspace |
|---|---|---|---|---|
| main | Asia | PA & System Architect | opus | workspace |
| homer | Homer | COO/Operations | opus | workspace-homer |
| frank | Frank | Head of Product & Eng | sonnet | workspace-frank |
| marco | Marco | Head of Marketing | sonnet | workspace-marco |

### Comunicazione
- **WhatsApp:** solo Asia ha accesso. Gli altri passano da Asia con `sessions_send`
- **Slack:** ogni agente ha la sua app (Socket Mode)
  - Workspace: `lorenzopinto.slack.com`
  - Canale condiviso: `#all-lorenzo-pinto` (`C0AFYSSBMJ7`) — requireMention, allowBots
- **Agent-to-agent:** `agentToAgent` abilitato per tutti
- **Telegram:** configurato ma groupPolicy "allowlist" con allowFrom vuoto → gruppi non funzionano

### Config file
- `~/.openclaw/openclaw.json` — ⚠️ CAUTELA: leggere prima di modificare, backup sempre

---

## 5. GitHub

- **Org:** `lorenzopinto-team` (owner: asia-volta)
- **PAT attivo:** `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` (repo, workflow, admin:org, write:packages)
- **Membri:** asia-volta, LorenzoPinto04, homer-lp, frank-lpt, marco-lpt
- **⚠️ REGOLA: tutti i repo DEVONO essere PRIVATI e sull'org** — mai repo pubblici, mai repo personali per progetti del team

**Repos:**
| Repo | Progetto | Visibility |
|------|----------|------------|
| agent-dashboard | Agent Dashboard | private ✅ |
| students-in-town-web | Students in Town | private ✅ |
| app-hub | App Hub | private ✅ |

---

## 6. Email

- **Provider:** Zoho Mail (mail.zoho.eu)
- **Dominio:** team.lorenzopinto.it
- **Account:** asia@, homer@, frank@, marco@ (tutti team.lorenzopinto.it)
- **⚠️ Gli agenti NON hanno accesso diretto** alla loro email Zoho. Account solo per identità/signups.
- **OAuth (Self Client):** configurato solo per Asia. Homer/Frank/Marco pending.
- **Gog CLI:** per `lorenzo@wearefutura.com` e `me@lorenzopinto.it` (Gmail/Google Workspace)

---

## 7. Notion

- **Workspace:** "Lorenzo Pinto's Notion" (me@lorenzopinto.it) — MAI Futura
- **Integrazione:** "Asia" (internal), ID `cac40c23-0105-4c64-93bb-f2dd348955f5`
- **Database principali:**
  - Projects: `31ddd070-5560-8148-814b-c72404e098c8`
  - Tasks: `31ddd070-5560-818c-a2e4-c20a0e35f531`
  - Decisions Log: `31ddd070-5560-81a9-87a0-f75b6be390c2`

---

## 8. Progetti

### Agent Dashboard
- **Path:** `~/.openclaw/projects/agent-dashboard/`
- **Stack:** Next.js v16.1.6, SQLite (better-sqlite3), Tailwind CSS
- **Server:** porta 3000 (locale), porta 3001 (tunnel Cloudflare)
- **Hosting attuale:** Netlify (`agent-dashboard-asia.netlify.app`) — in migrazione a Cloudflare
- **API:** `/api/usage`, `/api/sessions`, `/api/rate-limits`, `/api/fire`, `/api/tasks`, `/api/tasks/stream` (SSE)

### Students in Town (SiT)
- **Path:** `~/.openclaw/projects/students-in-town-web/`
- **Stack:** Next.js + Tailwind CSS, export statico
- **Hosting:** Cloudflare Pages (students-in-town.pages.dev / studentsintown.com)
- **Brief:** Notion → "🏠 Students in Town — Business Unit"

---

## 9. Cron Jobs

| Nome | Frequenza | Status | Note |
|------|-----------|--------|------|
| Vinted Inbox Monitor | ogni 2h | ⚠️ sessione scaduta | Serve re-login |
| Session Token Monitor | ogni 3h | attivo | Monitora token usage |
| Daily Review Serale | 22:00 | errore | Probabilmente rate limit |
| Morning inbox cleanup | 08:00 | attivo | Email lorenzo@wearefutura.com |
| Recap settimanale Futura | Ven 19:00 | errore | Da verificare |
| Agent heartbeats | 30 min | attivo | Homer/Frank/Marco |

---

## 10. Decisioni Chiave (Log)

| Data | Decisione | Motivo |
|------|-----------|--------|
| 2026-02-20 | Cloudflare come piattaforma unica | Già account, dominio, tunnel |
| 2026-02-20 | Homer su Opus | Ruolo coordinamento critico |
| 2026-02-23 | Paolo rimosso, fuso in Frank | Team piccolo, non serve separare product/eng |
| 2026-02-23 | Cautela modifiche config | Modifiche strutturali hanno rotto il gateway |
| 2026-03-08 | SQLite DB source of truth per task | tasks.json è solo export |
| 2026-03-09 | Carta team solo in workspace Asia | Sicurezza: altri agenti chiedono ad Asia |
| 2026-03-09 | Review timeout 2h | Asia approva come proxy dopo 2h senza risposta |
| 2026-03-09 | QA visiva obbligatoria pre-deploy | Dopo fallimento deploy SiT senza CSS |
| 2026-03-09 | NS cambio via pannello Register.it | Non serve ticket, c'è il form diretto |

---

## 11. Regole Operative

1. **Prima di qualsiasi modifica infrastrutturale:** leggi ARCHITECTURE.md
2. **Prima di creare qualcosa di nuovo:** verifica se esiste già
3. **Prima di scegliere un servizio:** verifica se ne usiamo già uno equivalente
4. **Backup config prima di modificarla**
5. **Mai dichiarare "done" senza QA visiva**
6. **Mai comunicare a Lorenzo senza aver verificato personalmente**
7. **Ogni nuova decisione architetturale va documentata qui**
8. **Tutti i repo GitHub SEMPRE privati e sull'org `lorenzopinto-team`**

---

## 12. Checklist Nuovo Progetto

Quando si crea un nuovo progetto, seguire TUTTI questi step:

1. **Repo GitHub** → creare su `lorenzopinto-team` (PRIVATO)
2. **Cloudflare Pages** → creare progetto e deployare
3. **DNS** → aggiungere CNAME `[nome].app.lorenzopinto.it` → `[progetto].pages.dev`
4. **Custom domain** → registrare su Cloudflare Pages
5. **App Hub** → aggiungere card in `~/.openclaw/projects/app-hub/index.html` e ri-deployare
6. **Dashboard** → aggiungere entry in `src/lib/projects.ts` della dashboard
7. **ARCHITECTURE.md** → aggiornare sezioni DNS, GitHub, Progetti
8. **Notion** → aggiungere entry nel Projects DB

---

*Ultimo aggiornamento: 2026-03-09 09:30*
*Aggiornato da: Asia*

Preview

ARCHITECTURE.md — Mappa Architetturale Completa

Scopo: Questo file è la fonte di verità per TUTTE le scelte architetturali del sistema. Regola: Prima di QUALSIASI modifica infrastrutturale, leggi questo file. Se la modifica contraddice una decisione documentata qui, FERMATI e chiedi.

1. Principi Architetturali

Cloudflare come piattaforma unica per DNS, domini, hosting, tunnel, Pages
Niente duplicazioni — un servizio per ogni funzione, non due
SQLite come source of truth per i task (tasks.db), tasks.json è solo export
WhatsApp come canale principale per Lorenzo (Telegram spesso non lo vede)
Solo Asia modifica infrastruttura — gli altri agenti non toccano config/architettura
Acquisti passano da Asia — carta del team nel suo workspace, budget autonomo < €100

2. Domini e DNS

lorenzopinto.it

Registrar: Register.it (login: LP43214-EURO) — NON si tocca più, tutto si gestisce da Cloudflare
NS: jobs.ns.cloudflare.com, rafe.ns.cloudflare.com (cambiati 2026-03-09)
Zona Cloudflare: ec676bad49549cbaaad39f96fa4ede8a (status: pending → active dopo propagazione NS, 24-48h)
DNS puliti il 2026-03-09: rimossi tutti i record vecchi Register.it (A, AAAA, MX, SRV, SPF)

Struttura sottodomini:

lorenzopinto.it                    → vuoto (nessun record A, da decidere in futuro)
app.lorenzopinto.it                → Hub Progetti (Cloudflare Pages: app-hub)
dashboard.app.lorenzopinto.it      → Agent Dashboard (tunnel Cloudflare)
sit.app.lorenzopinto.it            → Students in Town (Cloudflare Pages: students-in-town)

Pattern: tutte le app vanno sotto *.app.lorenzopinto.it, con app.lorenzopinto.it come hub/indice.

Record DNS attuali: | Nome | Tipo | Destinazione | |------|------|-------------| | app | CNAME | app-hub-8at.pages.dev (Pages) | | dashboard.app | CNAME | fd7e2b13-...cfargotunnel.com (tunnel) | | sit.app | CNAME | students-in-town.pages.dev (Pages) | | @ | TXT | google-site-verification (mantenuto) |

Cloudflare Pages projects: | Progetto | URL Pages | Custom domain | |----------|-----------|---------------| | app-hub | app-hub-8at.pages.dev | app.lorenzopinto.it | | students-in-town | students-in-town.pages.dev | sit.app.lorenzopinto.it, studentsintown.com |

Tunnel: mac-mini / fd7e2b13-dfa7-422f-86c7-7406568e19cd

Config: ~/.cloudflared/config.yml
Ingress: dashboard.app.lorenzopinto.it → http://localhost:3000
⚠️ Creato su account vecchio Lorenzo — verificare cross-account dopo propagazione NS

studentsintown.com

Registrar: Cloudflare Registrar (account Voltaasia)
Zona Cloudflare: 3b4b8ed9232ca62d76c9bbba13a5cfdd (status: active)
Hosting: Cloudflare Pages, progetto students-in-town
DNS:
- studentsintown.com → CNAME → students-in-town.pages.dev (proxied)
- www.studentsintown.com → CNAME → students-in-town.pages.dev (proxied)
Deploy: wrangler pages deploy out/ --project-name students-in-town
Scadenza dominio: 9 marzo 2027, auto-rinnovo attivo
Costo: $10.46/anno
Progetto locale: ~/.openclaw/projects/students-in-town-web/
Stack: Next.js + Tailwind CSS, export statico (next build → out/)

studentsintown.it

Non registrato. Cloudflare Registrar non supporta .it
Decisione: rimandata post-MVP. Se serve, usare Register.it o Aruba.

3. Cloudflare

Account

Account attivo (Voltaasia): bd4a9927815d17a941acc736bd6c2b1c — email: [email protected]
Account vecchio (Lorenzo): 9a22114a9e50dae583fe8feca63977cf — INACCESSIBILE (CAPTCHA bloccante)

API Tokens

| Nome | Token | Permessi | Scope | |------|-------|----------|-------| | DNS Edit | esIRWcs5ktFFRYHOYzPoQLJ6ZgijbJBuPNWBF6YL | Zone DNS Edit | Tutte le zone | | Pages Deploy | hgI0HA2U0UHFUSFslDvOprdtx_SvGk9CmQBlh6y5 | Pages Read + Write | Account Voltaasia |

Servizi in uso

Cloudflare Registrar — studentsintown.com
Cloudflare DNS — zone per lorenzopinto.it e studentsintown.com
Cloudflare Pages — hosting Students in Town
Cloudflare Tunnel — accesso dashboard agent (tramite account vecchio)

4. Team Multi-Agent (OpenClaw)

Agenti

| ID | Nome | Ruolo | Model | Workspace | |---|---|---|---|---| | main | Asia | PA & System Architect | opus | workspace | | homer | Homer | COO/Operations | opus | workspace-homer | | frank | Frank | Head of Product & Eng | sonnet | workspace-frank | | marco | Marco | Head of Marketing | sonnet | workspace-marco |

Comunicazione

WhatsApp: solo Asia ha accesso. Gli altri passano da Asia con sessions_send
Slack: ogni agente ha la sua app (Socket Mode)
- Workspace: lorenzopinto.slack.com
- Canale condiviso: #all-lorenzo-pinto (C0AFYSSBMJ7) — requireMention, allowBots
Agent-to-agent: agentToAgent abilitato per tutti
Telegram: configurato ma groupPolicy "allowlist" con allowFrom vuoto → gruppi non funzionano

Config file

~/.openclaw/openclaw.json — ⚠️ CAUTELA: leggere prima di modificare, backup sempre

5. GitHub

Org: lorenzopinto-team (owner: asia-volta)
PAT attivo: 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 (repo, workflow, admin:org, write:packages)
Membri: asia-volta, LorenzoPinto04, homer-lp, frank-lpt, marco-lpt
⚠️ REGOLA: tutti i repo DEVONO essere PRIVATI e sull'org — mai repo pubblici, mai repo personali per progetti del team

Repos: | Repo | Progetto | Visibility | |------|----------|------------| | agent-dashboard | Agent Dashboard | private ✅ | | students-in-town-web | Students in Town | private ✅ | | app-hub | App Hub | private ✅ |

6. Email

Provider: Zoho Mail (mail.zoho.eu)
Dominio: team.lorenzopinto.it
Account: asia@, homer@, frank@, marco@ (tutti team.lorenzopinto.it)
⚠️ Gli agenti NON hanno accesso diretto alla loro email Zoho. Account solo per identità/signups.
OAuth (Self Client): configurato solo per Asia. Homer/Frank/Marco pending.
Gog CLI: per [email protected] e [email protected] (Gmail/Google Workspace)

7. Notion

Workspace: "Lorenzo Pinto's Notion" ([email protected]) — MAI Futura
Integrazione: "Asia" (internal), ID cac40c23-0105-4c64-93bb-f2dd348955f5
Database principali:
- Projects: 31ddd070-5560-8148-814b-c72404e098c8
- Tasks: 31ddd070-5560-818c-a2e4-c20a0e35f531
- Decisions Log: 31ddd070-5560-81a9-87a0-f75b6be390c2

8. Progetti

Agent Dashboard

Path: ~/.openclaw/projects/agent-dashboard/
Stack: Next.js v16.1.6, SQLite (better-sqlite3), Tailwind CSS
Server: porta 3000 (locale), porta 3001 (tunnel Cloudflare)
Hosting attuale: Netlify (agent-dashboard-asia.netlify.app) — in migrazione a Cloudflare
API: /api/usage, /api/sessions, /api/rate-limits, /api/fire, /api/tasks, /api/tasks/stream (SSE)

Students in Town (SiT)

Path: ~/.openclaw/projects/students-in-town-web/
Stack: Next.js + Tailwind CSS, export statico
Hosting: Cloudflare Pages (students-in-town.pages.dev / studentsintown.com)
Brief: Notion → "🏠 Students in Town — Business Unit"

9. Cron Jobs

| Nome | Frequenza | Status | Note | |------|-----------|--------|------| | Vinted Inbox Monitor | ogni 2h | ⚠️ sessione scaduta | Serve re-login | | Session Token Monitor | ogni 3h | attivo | Monitora token usage | | Daily Review Serale | 22:00 | errore | Probabilmente rate limit | | Morning inbox cleanup | 08:00 | attivo | Email [email protected] | | Recap settimanale Futura | Ven 19:00 | errore | Da verificare | | Agent heartbeats | 30 min | attivo | Homer/Frank/Marco |

10. Decisioni Chiave (Log)

| Data | Decisione | Motivo | |------|-----------|--------| | 2026-02-20 | Cloudflare come piattaforma unica | Già account, dominio, tunnel | | 2026-02-20 | Homer su Opus | Ruolo coordinamento critico | | 2026-02-23 | Paolo rimosso, fuso in Frank | Team piccolo, non serve separare product/eng | | 2026-02-23 | Cautela modifiche config | Modifiche strutturali hanno rotto il gateway | | 2026-03-08 | SQLite DB source of truth per task | tasks.json è solo export | | 2026-03-09 | Carta team solo in workspace Asia | Sicurezza: altri agenti chiedono ad Asia | | 2026-03-09 | Review timeout 2h | Asia approva come proxy dopo 2h senza risposta | | 2026-03-09 | QA visiva obbligatoria pre-deploy | Dopo fallimento deploy SiT senza CSS | | 2026-03-09 | NS cambio via pannello Register.it | Non serve ticket, c'è il form diretto |

11. Regole Operative

Prima di qualsiasi modifica infrastrutturale: leggi ARCHITECTURE.md
Prima di creare qualcosa di nuovo: verifica se esiste già
Prima di scegliere un servizio: verifica se ne usiamo già uno equivalente
Backup config prima di modificarla
Mai dichiarare "done" senza QA visiva
Mai comunicare a Lorenzo senza aver verificato personalmente
Ogni nuova decisione architetturale va documentata qui
Tutti i repo GitHub SEMPRE privati e sull'org lorenzopinto-team

12. Checklist Nuovo Progetto

Quando si crea un nuovo progetto, seguire TUTTI questi step:

Repo GitHub → creare su lorenzopinto-team (PRIVATO)
Cloudflare Pages → creare progetto e deployare
DNS → aggiungere CNAME [nome].app.lorenzopinto.it → [progetto].pages.dev
Custom domain → registrare su Cloudflare Pages
App Hub → aggiungere card in ~/.openclaw/projects/app-hub/index.html e ri-deployare
Dashboard → aggiungere entry in src/lib/projects.ts della dashboard
ARCHITECTURE.md → aggiornare sezioni DNS, GitHub, Progetti
Notion → aggiungere entry nel Projects DB

Ultimo aggiornamento: 2026-03-09 09:30 Aggiornato da: Asia