# faithbase-ai/openfaith architecture

> Architecture diagram of the GitHub repository faithbase-ai/openfaith, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/faithbase-ai/openfaith
- Repository: https://github.com/faithbase-ai/openfaith

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "UI Layer"
        FA["Frontend Application<br/>(Remix/React)"]:::frontend
        RR["Remix Routes & SSR"]:::frontend
        FI["Frontend Auth Integration"]:::frontend
    end

    %% SDK & Client Sync
    subgraph "SDK & Client Sync"
        UIlib["UI Library"]:::sharedcomp
        Zero["Client Sync Engine"]:::sharedcomp
        LC["Local Cache / IndexedDB"]:::datastore
    end

    %% API Layer
    subgraph "API Layer"
        APILayer["HTTP/TRPC API"]:::backend
        APIRoot["API Root & Router Setup"]:::backend
    end

    %% Sync Engine & Workers
    subgraph "Sync Engine & Workers"
        SE["Sync Engine Workers & Scheduler"]:::backend
        CM["Connector Manager"]:::backend
        JS["Job Scheduler"]:::backend
        WI["Webhook Ingestor"]:::backend
        CR["Conflict Resolver"]:::backend
    end

    %% Adapters
    AdapterCore["Adapter Core Interface"]:::sharedcomp
    PCO["Planning Center Online Adapter"]:::sharedcomp
    OAuthHooks["OAuth Popup Hooks"]:::sharedcomp

    %% External Systems
    subgraph "External Systems"
        ChMS["External ChMS Systems"]:::external
    end

    %% Data Layer
    subgraph "Data Layer"
        DB["PostgreSQL"]:::datastore
        Redis["Redis"]:::datastore
    end

    %% Packages
    subgraph "Shared Packages"
        Schema["Canonical Data Model Schemas"]:::sharedcomp
        DBLayer["Database Layer<br/>(Drizzle ORM & Migrations)"]:::sharedcomp
        AuthLib["Auth & RBAC Library"]:::sharedcomp
        SharedUtil["Shared Utilities & Env Helpers"]:::sharedcomp
        SharedTypes["Shared Types"]:::sharedcomp
        RedisClient["Redis Client Lib"]:::sharedcomp
        ResendClient["Email Client Lib"]:::sharedcomp
    end

    %% Infra
    Infra["PostgreSQL Docker Compose"]:::infra

    %% Email Service
    EmailS["Email Service"]:::backend

    %% Connections
    FA -->|"routes load"| RR
    FA -->|"uses auth integration"| FI
    FA -->|"uses UI primitives"| UIlib
    FA -->|"uses client sync"| Zero
    Zero -->|"sync loop"| LC
    LC -->|"data access"| Zero
    FA -->|"trpc/fetch"| APILayer

    APILayer -->|"routes to"| APIRoot
    APILayer -->|"uses schema"| Schema
    APILayer -->|"queries"| DBLayer
    APILayer -->|"env/helpers"| SharedUtil
    APILayer -->|"auth checks"| AuthLib
    APILayer -->|"invoke sync"| SE

    FI -->|"auth calls"| AuthLib
    AuthLib -->|"session storage"| DB
    AuthLib -->|"cache/lock"| Redis

    SE --> CM
    SE --> JS
    SE --> WI
    SE --> CR
    CM --> AdapterCore
    AdapterCore --> OAuthHooks
    AdapterCore --> PCO
    PCO -->|"REST/Webhook"| ChMS
    SE -->|"persist state"| DB
    SE -->|"send email"| EmailS

    EmailS --> ResendClient

    Infra --> DB
    RedisClient --> Redis

    %% Click Events
    click FA "https://github.com/faithbase-ai/openfaith/tree/main/apps/openfaith"
    click RR "https://github.com/faithbase-ai/openfaith/tree/main/apps/openfaith/app"
    click FI "https://github.com/faithbase-ai/openfaith/tree/main/apps/openfaith/shared/auth"
    click UIlib "https://github.com/faithbase-ai/openfaith/tree/main/packages/ui"
    click Zero "https://github.com/faithbase-ai/openfaith/tree/main/packages/zero"
    click APILayer "https://github.com/faithbase-ai/openfaith/tree/main/backend/api"
    click APIRoot "https://github.com/faithbase-ai/openfaith/blob/main/backend/api/root.ts"
    click SE "https://github.com/faithbase-ai/openfaith/tree/main/backend/workers"
    click AuthLib "https://github.com/faithbase-ai/openfaith/tree/main/packages/auth"
    click Schema "https://github.com/faithbase-ai/openfaith/tree/main/packages/schema"
    click DBLayer "https://github.com/faithbase-ai/openfaith/tree/main/packages/db"
    click SharedUtil "https://github.com/faithbase-ai/openfaith/tree/main/packages/shared"
    click SharedTypes "https://github.com/faithbase-ai/openfaith/blob/main/packages/shared/types.ts"
    click RedisClient "https://github.com/faithbase-ai/openfaith/blob/main/packages/be-shared/redis/redisClient.ts"
    click ResendClient "https://github.com/faithbase-ai/openfaith/blob/main/packages/be-shared/resend/resendClient.ts"
    click AdapterCore "https://github.com/faithbase-ai/openfaith/tree/main/adapters/adapter-core"
    click OAuthHooks "https://github.com/faithbase-ai/openfaith/tree/main/adapters/adapter-core/hooks"
    click PCO "https://github.com/faithbase-ai/openfaith/tree/main/adapters/pco"
    click Infra "https://github.com/faithbase-ai/openfaith/blob/main/infra/db/docker-compose.yml"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#3399ff,color:#000;
    classDef backend fill:#d4edda,stroke:#28a745,color:#000;
    classDef datastore fill:#fff3cd,stroke:#ffcc00,color:#000;
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#000;
    classDef sharedcomp fill:#f5e6ff,stroke:#9b59b6,color:#000;
    classDef infra fill:#ffe6e6,stroke:#ff6666,color:#000;
```
