Cos'è questa applicazione

Il prototipo demo è costruito in HTML/React puro con dati fittizi. Per renderlo funzionante servono un backend, un database, un sistema di autenticazione e un'infrastruttura di deploy.

Stack consigliato

Stack moderno, open source, con ampia documentazione e community attiva. Ideale per team piccoli con budget limitato.

🖥️ Frontend

⚙️ Backend

🗄️ Database

☁️ Servizi cloud

Struttura del progetto

Architettura monorepo con frontend e backend separati, comunicanti tramite API REST JSON.

# Monorepo
associazione-app/
├── frontend/               # React + Vite
│   ├── src/
│   │   ├── components/     # Badge, Card, Modal, ecc.
│   │   ├── pages/          # Dashboard, Soci, Quote, ...
│   │   ├── hooks/          # useSoci, useEventi, ...
│   │   ├── api/            # client fetch, react-query
│   │   ├── i18n/           # traduzioni IT/EN
│   │   └── App.tsx
│   └── package.json
│
├── backend/                # Node.js + Express
│   ├── src/
│   │   ├── routes/         # /api/soci, /api/eventi, ...
│   │   ├── controllers/    # logica business
│   │   ├── models/         # schema Prisma/Sequelize
│   │   ├── middleware/     # auth, validazione, rate limit
│   │   ├── services/       # email, storage, pagamenti
│   │   └── app.js
│   └── package.json
│
├── database/
│   ├── migrations/         # versioni schema DB
│   └── seeds/              # dati iniziali demo
│
└── docker-compose.yml      # PostgreSQL + Redis locali

Flusso dati

Schema del database

Schema PostgreSQL normalizzato. Le relazioni tra tabelle garantiscono integrità referenziale.

Endpoint principali

Tutte le API restituiscono JSON. Prefisso base: /api/v1. Autenticazione tramite Bearer token JWT.

Esempio di risposta

// GET /api/v1/soci?stato=attivo&page=1&limit=20
{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716",
      "nome": "Marco Rossi",
      "email": "marco.rossi@email.it",
      "tessera": "2026-001",
      "ruolo": "volontario",
      "stato": "attivo",
      "quota_pagata": true
    }
  ],
  "meta": {
    "total": 8,
    "page": 1,
    "limit": 20,
    "pages": 1
  }
}

Sistema di accesso e ruoli

Autenticazione stateless con JWT (JSON Web Token). Tre livelli di accesso con permessi distinti.

Flusso di login

// POST /api/v1/auth/login
const login = async (req, res) => {
  const { email, password } = req.body;
  
  // 1. Trova utente nel DB
  const utente = await prisma.soci.findUnique({ where: { email } });
  if (!utente) return res.status(401).json({ error: "Credenziali non valide" });
  
  // 2. Verifica password con bcrypt
  const ok = await bcrypt.compare(password, utente.password_hash);
  if (!ok) return res.status(401).json({ error: "Credenziali non valide" });
  
  // 3. Genera JWT (scade in 7 giorni)
  const token = jwt.sign(
    { id: utente.id, ruolo: utente.ruolo },
    process.env.JWT_SECRET,
    { expiresIn: "7d" }
  );
  
  res.json({ token, utente: { id: utente.id, nome: utente.nome, ruolo: utente.ruolo } });
};

Come implementare ogni sezione

👥 Gestione Soci

• CRUD completo con validazione (email unica, formato tessera auto-generato)
• Ricerca full-text su nome, email, tessera tramite ILIKE PostgreSQL
• Export CSV con libreria csv-stringify (Node) o csv (Python)
• Generazione tessera digitale PDF con PDFKit o WeasyPrint
• Considerare l'upload foto profilo su S3/R2 con resize automatico

💳 Quote e Pagamenti

• Auto-generazione record quota ogni anno (job schedulato al 1° gennaio)
• Integrazione Stripe per pagamento online: webhook per aggiornare lo stato
• Invio sollecito automatico via email dopo 30/60/90 giorni di mancato pagamento
• Ricevuta PDF auto-generata dopo ogni pagamento confermato
• Attenzione alla normativa fiscale italiana per le ricevute (art. 148 TUIR)

📅 Eventi e Iscrizioni

• Gestione lista d'attesa quando iscritti >= max_iscritti
• Email di conferma iscrizione automatica con dettagli evento (template HTML)
• Esportazione lista partecipanti in PDF/CSV
• Reminder automatico 24h prima dell'evento
• Per eventi a pagamento, integrare Stripe Checkout

📁 Documenti

• Upload su S3/R2 con URL pre-firmati (scadono dopo 1h) per download sicuro
• Validazione tipo file (solo PDF, DOCX, XLSX) e dimensione max (20MB)
• Versionamento documenti: mantenere storico delle versioni precedenti
• Ricerca full-text nel contenuto dei PDF con pdftotext + indice PostgreSQL

💰 Bilancio

• Ogni transazione è immutabile (no UPDATE/DELETE): usa note di credito per correzioni
• Export XLSX con exceljs o openpyxl compatibile con contabilità standard
• Riepilogo IVA e rendiconto annuale conforme alle norme APS/ODV
• Conservare i giustificativi di ogni spesa (ricevute, fatture) come allegati

Sistema di comunicazioni automatiche

Job schedulati (cron)

import cron from 'node-cron';

// Ogni giorno alle 9:00 — sollecito quote scadute
cron.schedule('0 9 * * *', async () => {
  const morosi = await prisma.pagamenti.findMany({
    where: { stato: 'da_pagare', anno: new Date().getFullYear() }
  });
  for (const p of morosi) {
    await sendEmail(p.socio.email, 'sollecito-quota', { anno: p.anno });
  }
});

// Ogni giorno alle 8:00 — reminder evento domani
cron.schedule('0 8 * * *', async () => {
  const domani = new Date();
  domani.setDate(domani.getDate() + 1);
  const eventi = await prisma.eventi.findMany({
    where: { data_ora: { gte: domani, lt: addDays(domani, 1) } },
    include: { iscrizioni: { include: { socio: true } } }
  });
  // invia reminder a ogni iscritto...
});

Mettere online l'applicazione

Due opzioni principali: soluzione fully managed (più semplice) o VPS self-hosted (più economica nel lungo periodo).

Opzione A — Fully managed (consigliato per iniziare)

Opzione B — VPS self-hosted (per budget molto limitati)

# docker-compose.prod.yml
services:
  nginx:
    image: nginx:alpine
    ports: ["80:80", "443:443"]
    volumes: ["./nginx.conf:/etc/nginx/nginx.conf"]

  backend:
    build: ./backend
    environment:
      DATABASE_URL: postgres://user:pass@db:5432/associazione
      JWT_SECRET: "your-64-char-random-secret"
      RESEND_API_KEY: "re_..."

  db:
    image: postgres:16-alpine
    volumes: ["pgdata:/var/lib/postgresql/data"]
    environment:
      POSTGRES_DB: associazione
      POSTGRES_PASSWORD: "strong-password-here"

  redis:
    image: redis:7-alpine

volumes:
  pgdata:

Passi per il primo deploy

Best practice di sicurezza

• HTTPS ovunque — mai HTTP in produzione. Let's Encrypt per SSL gratuito.
• Rate limiting su tutte le API — max 100 req/min per IP con express-rate-limit
• Validazione input con zod (TypeScript) o Pydantic (Python) su ogni endpoint
• Sanitizzazione output — mai esporre password_hash, token interni, dati sensibili
• CORS configurato — whitelist solo il dominio frontend (no * in produzione)
• Headers di sicurezza — usare helmet.js per Content-Security-Policy, X-Frame-Options
• Backup automatico DB — dump giornaliero su S3 con retention 30 giorni
• Dati personali soci soggetti a GDPR — serve una privacy policy e registro trattamenti
• Log degli accessi — registrare chi ha letto/modificato dati sensibili (audit trail)
• Considera 2FA (TOTP) per gli account amministratore

Gestione nel tempo

Monitoraggio

Aggiornamenti annuali

Fasi di sviluppo consigliate

Alternative pronte all'uso

Se il budget di sviluppo è limitato, considera soluzioni SaaS esistenti già configurate per associazioni italiane: