Zum Hauptinhalt springen

API

Die ChurchApps-API ist ein modularer Monolith — eine einzige Codebasis, die sechs Datenmodule bedient, wobei jedes Modul seine eigene Datenbank hat. Diese Architektur bietet die organisatorischen Vorteile von Microservices (klare Grenzen, unabhängige Datenspeicher) bei der betrieblichen Einfachheit einer einzigen Bereitstellung.

Module​

ModulZweck
MembershipPersonen, Gruppen, Haushalte, Berechtigungen
AttendanceGottesdienste, Sitzungen, Check-in-Datensätze
ContentSeiten, Abschnitte, Elemente, Streaming
GivingSpenden, Fonds, Zahlungsabwicklung
MessagingUnterhaltungen, Benachrichtigungen, E-Mail
DoingAufgaben, Pläne, Zuweisungen

Technologie-Stack​

  • Laufzeitumgebung: Node.js 24.x mit TypeScript (ES-Module)
  • Framework: Express
  • Dependency Injection: Inversify (decoratorbasiertes Routing)
  • Datenbank: MySQL — eine Datenbank pro Modul, jede mit eigenem Verbindungspool
  • Authentifizierung: JWT-basierte Authentifizierung über CustomAuthProvider
  • Bereitstellung: AWS Lambda über das Serverless Framework v3

Ports​

ProtokollPortBeschreibung
HTTP8084Haupt-REST-API
WebSocket8087Echtzeit-Socketverbindungen

Lambda-Funktionen​

Bei der Bereitstellung in AWS läuft die API als sechs Lambda-Funktionen:

  • web -- Verarbeitet alle HTTP-Anfragen
  • socket -- Verwaltet WebSocket-Verbindungen
  • timer15Min -- Läuft alle 30 Minuten für E-Mail-Benachrichtigungen (der Name ist historisch bedingt)
  • timerMidnight -- Läuft täglich für Digest-E-Mails und Wartungsaufgaben
  • timerScheduledTasks -- Läuft täglich für fällige Automatisierungen und die Verarbeitung überfälliger Workflows
  • timerWebhooks -- Läuft jede Minute, um wartende ausgehende Webhooks zuzustellen

Gemeinsam genutzte Bibliotheken​

Die API hängt von zwei gemeinsamen ChurchApps-Paketen ab:

  • @churchapps/helpers -- Grundlegende Hilfsfunktionen (DateHelper, ApiHelper usw.)
  • @churchapps/apihelper -- Hilfsfunktionen für den Express-Server, einschließlich Authentifizierung, Datenbankhilfen und AWS-Integrationen
Info

Die API verwendet ES-Module ("type": "module" in package.json). Achten Sie darauf, dass Ihre Importe die ES-Modul-Syntax verwenden.

In diesem Abschnitt​

  • Lokale Einrichtung -- Klonen, konfigurieren und die API lokal ausführen
  • Datenbank -- Architektur mit einer Datenbank pro Modul, Schema-Skripte und Muster für den Datenzugriff
  • Modulstruktur -- Controller, Repositories, Modelle und Authentifizierung
  • API-Schlüssel -- Persönliche Zugriffstoken für Skripte und Connectors
  • Connected Apps (OAuth) -- Mandantenfähiger OAuth-Ablauf für Apps von Drittanbietern
  • Webhooks -- Ereignisbenachrichtigungen an externe Systeme senden
  • MCP-Server -- Model-Context-Protocol-Endpunkt, der die API für KI-Assistenten bereitstellt
  • Endpunkt-Referenz -- Vollständige REST-API-Dokumentation für alle Module