Focolari-Voting-System/README.md

🗳️ Focolari Voting System

Sistema di controllo accessi per le assemblee di voto del Movimento dei Focolari.

📖 Descrizione

Applicazione web ottimizzata per tablet che gestisce i varchi d'ingresso alle sale votazione. Il sistema utilizza lettori RFID USB (che emulano tastiera) per identificare validatori e partecipanti.

🏗️ Struttura Progetto

VotoFocolari/
├── dev.sh            # Script sviluppo (install, dev, server, build, ...)
├── ai-prompts/       # Documentazione sviluppo e prompt
├── backend-mock/     # API mock in Python FastAPI
│   └── static/       # Frontend buildato (generato)
└── frontend/         # App React + TypeScript + Tailwind

🚀 Quick Start

Setup Iniziale

./dev.sh install

Sviluppo (hot reload)

./dev.sh dev
# Backend API: http://localhost:8000
# Frontend Dev: http://localhost:5173

Produzione Locale

./dev.sh server
# App completa: http://localhost:8000

Altri Comandi

./dev.sh build      # Solo build frontend
./dev.sh backend    # Solo backend (API)
./dev.sh frontend   # Solo frontend dev
./dev.sh shell      # Shell pipenv backend
./dev.sh clean      # Pulisce build e cache
./dev.sh help       # Mostra tutti i comandi

📚 Documentazione

Per dettagli tecnici, consulta la cartella ai-prompts/:

• 00-welcome-agent.md - Panoramica progetto
• 01-backend-plan.md - Piano sviluppo backend
• 02-frontend-plan.md - Piano sviluppo frontend

🔐 Credenziali Test

• Password Validatore: focolari
• Badge Test: Qualsiasi badge (es. 0008988288, 0007399575)

I badge di test con anagrafica sono documentati in backend-mock/API_SPECIFICATION.md.

🔍 Debug

Accedi a /debug per diagnostica RFID in tempo reale.

---

🏭 Build e Deploy in Produzione

Compilazione Frontend

Il frontend React deve essere compilato in file statici prima del deploy.

# Build automatica (usa dev.sh)
./dev.sh build

# Oppure manualmente
cd frontend
npm install
npm run build

I file compilati vengono generati in frontend/dist/.

Struttura Build Output

frontend/dist/
├── index.html
├── favicon.jpg
└── assets/
    ├── index-XXXXX.js      # Bundle JS minificato
    ├── index-XXXXX.css     # CSS minificato
    └── FocolareMovLogo-XXXXX.jpg

Deploy

Opzione 1: Backend Mock (test/demo)

Il backend mock Python serve automaticamente il frontend dalla cartella frontend/dist/:

./dev.sh server --host 0.0.0.0 --port 8000

L'applicazione completa sarà disponibile su http://<IP>:8000/.

Opzione 2: Backend Reale

Il backend di produzione deve:

1. Implementare le API secondo le specifiche in backend-mock/API_SPECIFICATION.md
2. Servire i file statici dalla cartella frontend/dist/ sulla root /
3. Configurare CORS se frontend e backend sono su domini diversi

Esempio con un web server (nginx, Apache, etc.):

server {
    listen 80;
    server_name voting.focolari.org;

    # Frontend statico
    location / {
        root /var/www/focolari/frontend/dist;
        try_files $uri $uri/ /index.html;
    }

    # API proxy verso backend
    location /info-room { proxy_pass http://localhost:8080; }
    location /login-validate { proxy_pass http://localhost:8080; }
    location /anagrafica/ { proxy_pass http://localhost:8080; }
    location /entry-request { proxy_pass http://localhost:8080; }
}

Opzione 3: Tutto-in-uno (consigliata)

Il backend reale serve direttamente i file statici:

# Esempio FastAPI
from fastapi.staticfiles import StaticFiles
from fastapi.responses import FileResponse

app.mount("/assets", StaticFiles(directory="frontend/dist/assets"))

@app.get("/")
async def serve_frontend():
    return FileResponse("frontend/dist/index.html")

Variabili d'Ambiente

Il frontend non richiede variabili d'ambiente. Le API sono chiamate con path relativi (/info-room, etc.), quindi funziona automaticamente indipendentemente dal dominio o porta.

Requisiti Sistema Produzione

• Python 3.11+ con pipenv (per backend mock)
• Node.js 18+ con npm (solo per build frontend)
• Browser moderno (Chrome, Safari, Firefox) sul tablet
• Lettore RFID configurato come tastiera HID

---

📄 Licenza

Progetto privato - Movimento dei Focolari