Component View
The component view (C4 Level 3) shows the internal architecture of the PSI backend and frontend containers.
Backend Components
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, andusersas core server modules. These are no longer separate source modules in the current codebase — authentication moved intoserver/auth/, and several concerns were consolidated. Refer toserver/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 notopicmigrationserver module in the current source.
Frontend Components
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
REPLACEwrapper fully replaces instead of appending- Deduplication by
keyfield; highestprioritywins
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
TopicandSimple Commentsas 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:
- API Router Dispatch -- Hono middleware, module resolution, admin authorization
- Auth Adapter Stack -- better-auth, Firebase, OIDC plugin chain
- Database Adapter -- ServerStore, Firebase vs MongoDB, client adapters
- Moderation Pipeline -- two-pass AI flow, prompts, pre-mod review
- Plugin System -- structures, features, config slot resolution
- Translation Adapter -- multi-language content translation
Further Reading
- Authentication Flow -- how SSO and login work end-to-end
- Data Model -- detailed data access patterns
- Adapter Pattern -- how adapters enable swappable implementations
- Design concepts (psi-product) -- full developer reference