Skip to content

Component View

The component view (C4 Level 3) shows the internal architecture of the PSI backend and frontend containers.

Backend Components

PSI Backend - Component Diagram

API Request Lifecycle

Every API request follows this path:

sequenceDiagram
    participant Client as PSI Frontend
    participant Router as API Router
    participant Auth as Auth Adapter
    participant Store as ServerStore
    participant Module as Module Function
    participant DB as Database Adapter

    Client->>Router: POST /api/{moduleId}/{functionId}
    Router->>Auth: Verify Authorization header (Firebase ID token)
    Auth-->>Router: Session with user identity
    Router->>Store: Create scoped ServerStore(silo, structure, instance, user)
    Router->>Module: Call module.publicFunctions[functionId](store, params)
    Module->>Store: Read data (getCollection, getObject, getModuleData)
    Store->>DB: Delegate to database adapter
    DB-->>Store: Data result
    Store-->>Module: Data
    Module->>Store: Write data (setObject, addObject, setModuleData)
    Note over Store: Writes are batched, not yet committed
    Module-->>Router: Function returns
    Router->>Store: Commit batched writes
    Store->>DB: Execute all writes atomically
    Router-->>Client: JSON response

Core Server Modules

The backend is organized into server module files under server/modules/ (~38 core module source files, plus index/registry and helper files). Modules export publicFunctions and/or adminFunctions and are dispatched by the API router. Core modules include:

Module Purpose
admin Admin user management, roles
analytics Event logging via Cloud Logging (feeds BigQuery)
article Article management
blocklist Server-side blocklist storage and pre-moderation gate
bookmarks User bookmarks
channels Conversation channel management
comments Comment CRUD and moderation dispatch
content-translation Multi-language automatic content translation
database Database operations
debug Environment inspection, email template rendering
derivedviews Derived view trigger system (object + global triggers)
health Health check endpoints (/health/live)
language Language settings
moderation In-process AI pre-moderation pipeline (two-pass LLM), review queue, judgements, email notifications
moderation-heat Heat-map moderation analytics
moderation-note Moderator notes
moderation-notification Moderation-related notifications
moderation-queue Moderation review queue
moderation-task-lock Moderation task locking
notifications Reply notification emails
perspectives Perspective management
poll-options / poll-votes Poll question support
premod-review Pre-moderation review data collection for AI accuracy auditing (GDPR TTL)
profile User profile management
pseudonym Pseudonym management
puppet Test user puppet system (secret-protected)
questions Question metadata and configuration
ranking GPT-based comment quality/bridging scoring
ranking-eval Ranking evaluation
related-content Related content linking
subscription Subscriptions
suspension User warn/block/unblock with expiry tracking
translation-queue Translation queue processing
users User management

Note: Older documentation listed modules such as auth, constructor, devlogin, global, jigsaw, notifs, topics, and users as core server modules. These are no longer separate source modules in the current codebase — authentication moved into server/auth/, and several concerns were consolidated. Refer to server/modules/ for the authoritative list.

Partner Open Modules (Server)

Partner Modules
ZDF article, article-teaser-position, conversation-helper, moderation, videovoting
SRG dialogue-labels

CBC/RC contributes client-side features (OIDC providers cbcRc, titled-writer, badges) rather than server modules. There is no topicmigration server module in the current source.


Frontend Components

PSI Frontend - Component Diagram

Structure + Feature Plugin Architecture

The frontend's core design pattern:

Structure (e.g. Question)
  ├── Defines screens (main, composer, ...)
  ├── Defines config slots (widgets, callbacks, data)
  │
  ├── Feature: comment-slider
  │     └── Fills pageTopWidgets slot
  ├── Feature: reactions
  │     └── Fills commentActionWidgets slot
  ├── Feature: moderation
  │     └── Fills commentPostCheckers callback
  │     └── Sub-feature: ai-moderation
  │     └── Sub-feature: manual-moderation
  └── Feature: pin-comment
        └── Fills commentHeaderWidgets slot

Features are enabled per-instance. Different instances of the same structure can have different features active. Feature config values are merged using these rules:

  • Arrays are appended across features
  • REPLACE wrapper fully replaces instead of appending
  • Deduplication by key field; highest priority wins

Core Structures

Structure Type Description
Question Multi-instance A question users can answer (one answer per user); also the SPACE structure-key
Profile Multi-instance User profile with name, photo, and feature widgets
Article Multi-instance Content item that questions/topics attach to; also the STORY structure-key
Admin Singleton Admin dashboard with links to management tools
Editorial Dash Singleton Create and browse questions/topics
Moderation Dash Singleton Content moderation interface
Login Singleton Login screen with SSO provider selection
Component Demo Singleton Design system component showcase
Account Singleton User's own account information
Settings Singleton User settings
Developer Tools Singleton Debug and inspection tools
Ranking Eval Singleton Ranking evaluation tools
Test Structure Singleton Automated testing structure
Video Voting ZDF / Multi-instance ZDF video voting structure (open-modules/zdf/structure/videovoting.tsx)

Note: Earlier documentation listed Topic and Simple Comments as core structures. Neither exists in the current codebase. In total there are 13 structures (12 core + ZDF Video Voting), not 18.

Client Database Adapters

Adapter Mode Description
FirebaseDatabaseAdapter Direct Connects directly to Firebase RTDB via SDK (default)
ServerDatabaseAdapter Proxied All data proxied through the PSI backend API
DemoDatabaseAdapter In-memory For tests and demos, no external dependency

The adapter is selected per-silo via configuration in psi.config.ts.

Next Level

Zoom into the Code Level (C4 Level 4) diagrams for detailed class and sequence diagrams of key subsystems:

Further Reading