Vai al contenuto principale

API

L'API di ChurchApps è un monolite modulare -- un'unica base di codice che serve sei moduli dati, ciascuno con il proprio database. Questa architettura offre i vantaggi organizzativi dei microservizi (confini chiari, archivi dati indipendenti) con la semplicità operativa di un unico deployment.

Moduli​

ModuloScopo
MembershipPersone, gruppi, nuclei familiari, permessi
AttendanceCulti, sessioni, record di check-in
ContentPagine, sezioni, elementi, streaming
GivingDonazioni, fondi, elaborazione dei pagamenti
MessagingConversazioni, notifiche, email
DoingAttività, piani, assegnazioni

Stack tecnologico​

  • Runtime: Node.js 24.x con TypeScript (moduli ES)
  • Framework: Express
  • Dependency Injection: Inversify (routing basato su decoratori)
  • Database: MySQL -- un database per modulo, ciascuno con il proprio pool di connessioni
  • Autenticazione: autenticazione basata su JWT tramite CustomAuthProvider
  • Deployment: AWS Lambda tramite Serverless Framework v3

Porte​

ProtocolloPortaDescrizione
HTTP8084API REST principale
WebSocket8087Connessioni socket in tempo reale

Funzioni Lambda​

Quando viene distribuita su AWS, l'API viene eseguita come sei funzioni Lambda:

  • web -- Gestisce tutte le richieste HTTP
  • socket -- Gestisce le connessioni WebSocket
  • timer15Min -- Viene eseguita ogni 30 minuti per le notifiche email (il nome è storico)
  • timerMidnight -- Viene eseguita ogni giorno per le email di riepilogo e le attività di manutenzione
  • timerScheduledTasks -- Viene eseguita ogni giorno per le automazioni in scadenza e l'elaborazione dei flussi di lavoro in ritardo
  • timerWebhooks -- Viene eseguita ogni minuto per inviare i webhook in uscita in coda

Librerie condivise​

L'API dipende da due pacchetti condivisi di ChurchApps:

Info

L'API usa i moduli ES ("type": "module" in package.json). Assicurati che i tuoi import usino la sintassi dei moduli ES.

In questa sezione​

  • Setup locale -- Clona, configura ed esegui l'API in locale
  • Database -- Architettura con un database per modulo, script dello schema e schemi di accesso ai dati
  • Struttura del modulo -- Controller, repository, modelli e autenticazione
  • Chiavi API -- Token di accesso personali per script e connettori
  • App collegate (OAuth) -- Flusso OAuth multi-tenant per app di terze parti
  • Webhook -- Invio di notifiche di eventi a sistemi esterni
  • Server MCP -- Endpoint Model Context Protocol che espone l'API agli assistenti IA
  • Riferimento degli endpoint -- Documentazione REST completa dell'API per tutti i moduli