Architecture Guidelines

These guidelines govern architectural decisions for the PSI project.

Core Principles

Modular Plugin Architecture

All functionality is built around the Structure + Feature model:

• Structures define content types and screens with extension points (config slots)
• Features fill those extension points with widgets, callbacks, and data
• Features are enabled per-instance, allowing different configurations for different conversations
• New functionality should be implemented as features whenever possible

Adapter Pattern

External service integrations must use the adapter pattern:

• Define an interface for the capability (auth, database, email, LLM)
• Implement the interface for each provider
• Select the implementation via configuration (environment variables)
• Application code only depends on the interface, never on a specific provider

Instance Isolation

Data access must respect instance isolation:

• Client code (via Datastore) can only access the current instance's data
• Server code (via ServerStore) is scoped to the requesting instance
• Cross-instance access requires explicit Remote methods, triggering closer code review
• Module data is namespaced to the module that owns it

Minimal Server Code

Server-side code should be minimized:

• Most features should be client-only
• Use standardized data abstractions (moduleData, collections, properties) instead of custom server endpoints
• Server code has higher blast radius -- prefer generalized, reusable API patterns

Technology Guidelines

Backend Services

• Implemented as microservices that can be developed and deployed in no more than two sprints
• Each service should serve a single purpose
• Services must not require global state or external dependencies beyond declared adapters
• Backend services should use compilable/type-safe languages (TypeScript)

Data Exchange Protocols

Frontend

• Cross-platform via Expo / React Native for Web
• File-system routing via expo-router
• Reusable components following the PSI Design System (Figma-driven)
• All UI components use React Native StyleSheet (not CSS)

Databases

• Primary: Firebase Realtime Database (NoSQL JSON, real-time sync)
• Alternative: MongoDB (via adapter, for non-Firebase deployments)
• Application code must use Datastore / ServerStore -- never access the database directly
• Data schemas must work across both database backends

Multi-Tenancy

PSI uses a silo-based multi-tenancy model:

• One silo per partner (e.g., zdf, cbc, rc, srg)
• Silos share the same codebase and deployment but have isolated data
• Each silo has its own configuration: language, features, theme, SSO providers
• Silos are configured in psi.config.ts (client) and database entries (server)

Open-Source Governance

• The codebase is open-source under Apache License 2.0
• Core modules are maintained by the PSI core team with full review (design, product, engineering)
• Open modules are maintained by contributing partners with minimal core review
• Core modules must not depend on open modules
• All modules must provide tests sufficient to detect regressions