PSI Architecture Documentation
PSI (Public Spaces Incubator) is an international open-source project building a modular toolkit for creating pro-social online conversation spaces. It is developed collaboratively by four public media broadcasters -- CBC/Radio Canada, RTBF, SRG SSR, ZDF -- plus the non-profit New Public.
This site provides the high-level architecture documentation for PSI, including C4 diagrams, system context, deployment architecture, and integration patterns. For detailed developer documentation (API reference, feature development, contribution guides), see the psi-product repository.
Quick Links
| Section | Description |
|---|---|
| Project Background | What PSI is, who builds it, and why |
| System Landscape | C4 Level 1: all systems in the PSI ecosystem |
| Container View | C4 Level 2: internal containers of the PSI system |
| Component View | C4 Level 3: backend and frontend components |
| Code Level (C4 Level 4) | Detailed code diagrams: routing, auth, database, moderation, plugins, translation |
| Authentication Flow | SSO/OIDC authentication and registration sequences |
| Deployment Overview | How to deploy PSI (Firebase, Docker, partner instances) |
| CI/CD Pipeline | GitHub Actions workflows |
The C4 Model
This documentation uses the C4 model to describe the PSI architecture at multiple zoom levels:
- System Landscape -- All systems and people involved
- Container -- The major deployable units within PSI (frontend, backend, databases, etc.)
- Component -- Internal structure of key containers (backend modules, frontend plugin architecture)
- Code -- Detailed class/module diagrams for key subsystems (moderation, auth, database, plugins, translation, routing)
Interactive C4 diagrams are available via the Structurizr workspace. Static diagrams are embedded throughout this documentation.
Technology Stack at a Glance
| Layer | Technology |
|---|---|
| Frontend | Expo SDK 54 (React Native for Web), expo-router, TypeScript |
| Backend | Hono, Firebase Cloud Functions / standalone Docker, TypeScript |
| Primary Database | Firebase Realtime Database |
| Alternative Database | MongoDB 6+ (via adapter) |
| Authentication | Firebase Auth + better-auth, OIDC SSO (Keycloak, Azure AD B2C, RTBF, NPO, SRG, Google) |
| AI Moderation | OpenAI (two-pass: gpt-4o-mini + gpt-4o), Google Perspective API |
| Postmark / SendGrid / SMTP | |
| Monitoring | Sentry (client + server) |
| Analytics | Google BigQuery |
| Translation | DeepL / TextShuttle / SRG SSR / OpenAI (LLM) |
| CI/CD | GitHub Actions, Firebase CLI |
| Package Manager | pnpm 10 (monorepo workspace) |
Repository Structure
The PSI project spans multiple repositories:
| Repository | Purpose |
|---|---|
psi-product | Main application code (client, server, moderation service, demos) |
psi-arch | This repo: architecture documentation, C4 diagrams, Structurizr workspace |
License
PSI is open source under the Apache License 2.0.