Skip to content

Adapter Pattern

PSI uses an adapter pattern extensively to decouple the core application logic from specific service implementations. This enables database portability, provider switching, and easier testing.

There are 4 server-side adapter categories (Auth, Database, Email, LLM/Translation dispatch) and 2 client-side adapters (Auth, Database). Note: auth lives under server/auth/ (not server/adapter/auth/); translation lives under server/adapter/translation/.

Adapter Overview

graph LR
    subgraph "Core Application"
        API[API Logic / Modules]
        API --> AuthI[Auth Adapter Interface]
        API --> DBI[Database Adapter Interface]
        API --> EmailI[Email Adapter Interface]
        API --> LLMI[LLM Adapter Interface]
    end

    subgraph "Auth Implementations"
        AuthI --> FBAuth[firebaseAuthAdapter]
        AuthI --> MongoAuth[databaseAdapter / mongodbAdapter]
    end

    subgraph "Database Implementations"
        DBI --> FBDB[Firebase RTDB Adapter]
        DBI --> MongoDB[MongoDB Adapter]
    end

    subgraph "Email Implementations"
        EmailI --> PM[Postmark Adapter]
        EmailI --> SG[SendGrid Adapter]
        EmailI --> SMTP[SMTP Adapter]
    end

    subgraph "LLM Implementations"
        LLMI --> OAI[OpenAI Adapter]
        LLMI --> Azure[Azure OpenAI Adapter]
        LLMI --> Vercel[Vercel AI Adapter]
        LLMI --> ZDF[ZDF OpenAI Adapter]
    end

    subgraph "Translation Implementations"
        API --> TransI[Translation Adapter Interface]
        TransI --> TLLM[LLM Adapter / OpenAI]
        TransI --> DeepL[DeepL Adapter]
        TransI --> TS[TextShuttle Adapter]
        TransI --> SRG[SRG SSR Adapter]
        TransI --> Offline[Offline Debug Adapter]
    end

Server-Side Adapters

Auth Adapter

Located in server/auth/ (not server/adapter/auth/). Manages user authentication, session management, and SSO token conversion.

Implementation stack (better-auth, server/auth/):

  1. firebaseAuthAdapter (server/auth/adapters/firebase-auth.ts) -- Firebase Authentication adapter factory (selected when AUTH_ADAPTER=firebase, the default)
  2. mongodbAdapter -- better-auth's bundled MongoDB adapter (selected when AUTH_ADAPTER=mongodb)
  3. firebase plugin (server/auth/plugins/firebase.ts) -- issues Firebase custom tokens and verifies Firebase ID tokens
  4. genericOidc plugin (server/auth/plugins/generic-oidc/) -- verifies JWTs from any OIDC provider via JWKS; provider-specific helpers for Azure AD B2C and CBC/RC

Selection: AUTH_ADAPTER environment variable (default: firebase)

Note: There is no BetterAuthAdapter base class or firebaseIdToken plugin. The Firebase integration is the firebaseAuthAdapter plus the firebase plugin.

Server-Side Adapters

Database Adapter

Located in server/adapter/database/. Abstracts all data storage operations.

Implementation Module Configuration
Firebase RTDB firebase-adapter.ts Default (when using Firebase)
MongoDB mongodb-adapter.ts DATABASE_ADAPTER=mongodb + MONGODB_URL

Both adapters implement the same interface for reading/writing instances, collections, module data, and silo configurations. The MongoDB adapter uses compound-prefixed document IDs for data locality.

Email Adapter

Located in server/adapter/email/. Sends transactional emails (notifications, verification).

Implementation Configuration
Postmark EMAIL_PROVIDER=postmark + POSTMARK_API_KEY
SendGrid EMAIL_PROVIDER=sendgrid + SENDGRID_API_KEY
SMTP EMAIL_PROVIDER=smtp + SMTP_MAIL_SERVER, SMTP_USER, SMTP_PASSWORD

LLM Adapter

Located in server/adapter/llm/. Provides AI capabilities for moderation and content analysis.

Implementation Configuration
OpenAI OPENAI_PROVIDER=openai + OPENAI_KEY
Azure OpenAI OPENAI_PROVIDER=azure_openai + AZURE_OPENAI_KEY
Vercel AI OPENAI_PROVIDER=vercel_ai
ZDF OpenAI OPENAI_PROVIDER=zdf_openai

Perspective/toxic scoring is not a separate external API adapter in the current pipeline — the "perspective" moderation flows through the LLM (server/prompts/moderatePerspective.txt).

Translation Adapter

Located in server/adapter/translation/. Translates user-generated content between languages for multi-language silos.

Implementation Configuration
LLM (OpenAI) TEXT_TRANSLATION_PROVIDER=llm (default)
DeepL TEXT_TRANSLATION_PROVIDER=deepl + DEEPL_API_KEY
TextShuttle TEXT_TRANSLATION_PROVIDER=textshuttle + TEXT_SHUTTLE_API_KEY
SRG SSR TEXT_TRANSLATION_PROVIDER=srgssr-crknews-translation-api + SRG_TRANSLATION_API_URL
Offline Debug TEXT_TRANSLATION_PROVIDER=offlineDebug

The translation adapter is selected per-silo. For example, SRG uses their enterprise translation API while other silos default to LLM-based translation via OpenAI.

Client-Side Adapters

Client Auth Adapter

Located in client/adapter/auth/.

interface AuthAdapter {
    getCurrentUser(): User | null;
    getIdTokenAsync(): Promise<string>;
    signOutAsync(): Promise<void>;
    signInWithGoogleAsync(): Promise<void>;
    signInWithTokenAsync(token: string): Promise<void>;
    onAuthStateChanged(callback): Unsubscribe;
}

Default implementation: FirebaseAuthAdapter using the Firebase Auth SDK.

Client Database Adapter

Located in client/adapter/database/.

Adapter When Used
FirebaseDatabaseAdapter Default -- direct Firebase RTDB connection via SDK
ServerDatabaseAdapter When silo is configured with databaseAdapter: 'server'
DemoDatabaseAdapter Tests and demos -- in-memory, no external dependency

The ServerDatabaseAdapter proxies all reads and writes through the PSI backend API, which is useful for deployments where clients shouldn't have direct database access.

Benefits

Benefit How Adapters Help
Database portability Switch from Firebase RTDB to MongoDB without changing application code
Provider flexibility Partners can use their preferred email or AI service
Testability In-memory adapters (DemoDatabaseAdapter, mongo mock) enable fast tests
Gradual migration New adapters can be introduced alongside existing ones
Security ServerDatabaseAdapter prevents direct client-to-database access

Adding a New Adapter

To add a new implementation:

  1. Create a new file in the appropriate adapter/ subdirectory
  2. Implement the adapter interface
  3. Add a configuration option to select the adapter (typically an environment variable)
  4. Register the adapter in the initialization code

See the MongoDB Adapter documentation for a concrete example.