How faithbase-ai/openfaith works
Project type and purpose
• OpenFaith is a full-stack, monorepo application built with a Turborepo structure.
• It provides a universal sync & data platform for church management:
• A frontend application (Remix/React) under apps/openfaith
• A backend API & sync engine under backend/
• A suite of reusable packages (adapters, schema, database, UI, auth, sync)
File structure
• Top-level directories:
• adapters/ – code-first connectors for external ChMS systems (adapter-core, pco)
• apps/openfaith/ – the end user Remix frontend (routes, components, data hooks)
• backend/ – API layer (trpc, Express or similar), email service, background workers
• packages/ – shared libraries:
– db (Drizzle ORM & migrations)
– schema (canonical data model)
– auth (AuthN/AuthZ)
– zero (client-sync engine)
– ui (React component library)
– be-shared (Redis, email clients)
– shared (env, helper functions)
• infra/db – Docker Compose for PostgreSQL
• tooling – ESLint and TypeScript configs
README insights
• Core architectural principles: Canonical Data Model (CDM), Adapter/Connector pattern, Sync Engine, AI-First Layers, Schema-Driven design
• Key components described: Sync Engine (Connector Manager, Job Scheduler, Webhook Ingestor, Conflict Resolution), API layer, Frontend SDK, Client Sync
1. Frontend Application (apps/openfaith)
– React/Remix routes & UI components
– Uses packages/ui and packages/zero for UI and client sync
– Calls API via fetch/trpc client (packages/shared/getApiUrl & authClient)
2. Frontend SDK & Client Sync (packages/ui + packages/zero)
– UI primitives, dynamic schema-driven forms
– Zero client for local-first data sync
3. API Layer (backend/api)
– HTTP endpoints & trpc router
– SSR/session/token handlers in apps/openfaith/app/server
4. Auth & RBAC (packages/auth + apps/openfaith/shared/auth)
5. Sync Engine (backend/workers + backend/api root)
– Connector Manager that loads adapters/adapter-core
– Job Scheduler & Worker processes
– Webhook Ingestor
– State Manager & Conflict Resolver
6. Adapters (adapters/adapter-core + adapters/pco + other adapters)
– Adapter interface (mkAdapter) for external ChMS
– Transformer modules for mapping to/from CDM
7. Database (infra/db → PostgreSQL)
– Tables defined via packages/db (Drizzle ORM)
– Canonical Data Model schemas under packages/schema
8. External ChMS Systems
– Planning Center Online, Breeze, etc.
9. Supporting Services
– Redis (packages/be-shared/redis)
– Email service (backend/email, packages/be-shared/resend)
• Frontend App → API Layer (HTTP/TRPC calls)
• Frontend SDK ←→ Client Sync ←→ Local Cache / IndexedDB
• API Layer ↔ Database (Drizzle/PostgreSQL)
• API Layer → Sync Engine (invoke sync jobs, query status)
• Sync Engine ↔ Adapters (load connector, call CRUD/transform methods)
• Adapters ↔ External ChMS (REST/Webhook)
• Sync Engine → Database (persist sync state, canonical entities)
• API Layer → Auth Service → Database (for sessions, RBAC)
• Workers → Email Service (send invites, OTPs)
c. Architectural patterns & principles
• Monorepo with Turborepo: share code, orchestrate builds
• Adapter/Connector plugin pattern for external integrations
• Schema-Driven CDM (Effect Schema) under packages/schema
• Micro-services style separation: API, Workers, Adapters
• Client-Sync (Zero) for offline support
• AI-First tooling layer (conceptual; not yet implemented)
• Role-Based Access Control with contextual scoping
d. Key technologies & libraries
• Remix (React) for frontend
• TRPC or similar for type-safe APIs
• Drizzle ORM + PostgreSQL for data storage
• TypeScript throughout
• Redis for caching/locking (packages/be-shared/redis)
• Node workers (backend/workers)
• OAuth2 & popup flows (adapters/adapter-core/hooks)
• Zero for client sync