# 🗺️ Struttura Path del Sistema

## Riepilogo Configurazione Attuale

Il sistema Focolari Voting System utilizza una **struttura path separata** per frontend e API:

```
http://localhost:8000/
├── /badge              ← Frontend React SPA
│   ├── /               ← Pagina principale
│   ├── /debug          ← Pagina diagnostica
│   └── /assets/*       ← File statici (JS, CSS, immagini)
│
├── /api/*              ← API REST
│   ├── /info-room      ← Informazioni sala
│   ├── /login-validate ← Login validatore
│   ├── /anagrafica/{badge} ← Ricerca utente
│   └── /entry-request  ← Registrazione ingresso
│
├── /docs               ← Documentazione API (Swagger)
└── /                   ← Health check (solo se frontend non buildato)
```

---

## 🎯 Vantaggi di questa Struttura

1. **Separazione chiara**: Frontend e API sono completamente isolati
2. **Flessibilità**: Puoi cambiare il path del frontend senza toccare le API
3. **Sicurezza**: Le API sono su un path fisso, facile da proteggere con firewall/proxy
4. **Debugging**: È chiaro se un errore viene dal frontend o dalle API
5. **Deployment**: Puoi servire frontend e API da server diversi in futuro

---

## 📁 Files Coinvolti

### Backend

**File: `backend-mock/main.py`**
- Gestisce le route del frontend su `/badge`
- Include il router API che gestisce `/api/*`

**File: `backend-mock/api/routes.py`**
- Definisce tutte le route API con prefisso `/api/*`

### Frontend

**File: `frontend/src/main.tsx`**
- Configura il router React con `basename="/badge"`

**File: `frontend/src/services/api.ts`**
- Tutte le chiamate API usano il prefisso `/api/*`

**File: `frontend/vite.config.ts`**
- Proxy per development: `/api` → `http://127.0.0.1:8000`

**File: `frontend/playwright.config.ts`**
- Test E2E configurati per `baseURL: http://localhost:8000/badge`

**File: `frontend/e2e/app.spec.ts`**
- Intercept delle chiamate API su `**/api/entry-request`

---

## 🔄 Flusso Richieste

### In Sviluppo (Vite Dev Server)

```
Browser → http://localhost:5173/
          ↓
Frontend React (Vite)
          ↓
API call to /api/info-room
          ↓
Vite Proxy: /api/* → http://127.0.0.1:8000/api/*
          ↓
Backend FastAPI
```

### In Produzione (Server Integrato)

```
Browser → http://localhost:8000/badge
          ↓
Backend FastAPI
          ├─→ /badge → Serve frontend statico
          └─→ /api/* → Gestisce API REST
```

---

## 📋 Checklist Verifica

Per verificare che tutto funzioni correttamente:

```bash
# 1. Avvia il server
./dev.sh server

# 2. Testa il frontend
open http://localhost:8000/badge

# 3. Testa le API
curl http://localhost:8000/api/info-room
curl http://localhost:8000/api/anagrafica/0008988288

# 4. Verifica documentazione API
open http://localhost:8000/docs

# 5. Esegui i test E2E
./dev.sh test:e2e
```

---

## 🔧 Come Modificare

Per modificare i path, consulta **`CHANGE_BASE_PATH.md`** che spiega:

- Come cambiare il path del frontend (es. `/badge` → `/votazioni`)
- Come cambiare il path delle API (es. `/api/*` → `/v1/*`)
- Quali file modificare per ogni cambiamento
- Checklist completa di test

---

## 📊 Tabella Riassuntiva

| Componente | Path | Gestito da | File Config |
|------------|------|------------|-------------|
| **Frontend principale** | `/badge` | Backend (serve static) | `backend-mock/main.py` |
| **Frontend debug** | `/badge/debug` | Backend (serve static) | `backend-mock/main.py` |
| **Frontend assets** | `/badge/assets/*` | Backend (StaticFiles) | `backend-mock/main.py` |
| **Frontend router** | `/badge` (basename) | React Router | `frontend/src/main.tsx` |
| **API info sala** | `/api/info-room` | Backend API | `backend-mock/api/routes.py` |
| **API login** | `/api/login-validate` | Backend API | `backend-mock/api/routes.py` |
| **API anagrafica** | `/api/anagrafica/{badge}` | Backend API | `backend-mock/api/routes.py` |
| **API ingresso** | `/api/entry-request` | Backend API | `backend-mock/api/routes.py` |
| **Proxy dev** | `/api` → `:8000` | Vite | `frontend/vite.config.ts` |
| **Test E2E** | `baseURL: /badge` | Playwright | `frontend/playwright.config.ts` |

---

Documento creato: 2025-02-04  
Ultima modifica: 2025-02-04