Architecture Overview

This section describes the overall architecture of the Plus261 system, including the main components, data flow, security, and scalability considerations.

Monorepo Architecture

Plus261 uses a monorepo structure with shared libraries, ensuring type safety and code reuse across applications.

Deployment and runtime

Applications are packaged as container images (nerdctl) and run on Kubernetes:

• Local: k3d + Traefik — see Local development
• Production: k3s + Traefik + registry — see Production

Full picture: Infrastructure overview and Deployment.

General Architecture

Plus261 follows a monorepo architecture with clear separation of responsibilities:

┌─────────────────────────────────────────────────────────┐
│                    Web (SvelteKit)                      │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐ │
│  │   UI Layer   │  │  Offline DB  │  │ Chat & calls │ │
│  └──────────────┘  └──────────────┘  └──────────────┘ │
└───────────────────────┬─────────────────────────────────┘
                        │ GraphQL
                        │ WebSocket
┌───────────────────────▼─────────────────────────────────┐
│                  API (GraphQL Yoga)                      │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐ │
│  │  Auth/ACL    │  │  Business    │  │  Observability│ │
│  └──────────────┘  └──────────────┘  └──────────────┘ │
└───────────────────────┬─────────────────────────────────┘
                        │
┌───────────────────────▼─────────────────────────────────┐
│              PostgreSQL Database                         │
└─────────────────────────────────────────────────────────┘

Main Components

Web Client

The web client is a SvelteKit 5 application with offline-first architecture.

Component	Technology	Purpose
Framework	SvelteKit 5 with Svelte 5	Modern web framework
Local Storage	IndexedDB via Drizzle ORM	Offline data storage
Offline Mode	Service Worker	Offline operation and sync
Chat & calls	GraphQL subscriptions + LiveKit	Messaging, voice, calls
GraphQL	Generated client (@lib/client)	Type-safe API client

Learn more: Web Overview

API Server

The API is a GraphQL server built with GraphQL Yoga and Type GraphQL Query.

Component	Technology	Purpose
Framework	GraphQL Yoga	GraphQL server
Schema Builder	Type GraphQL Query	Automatic schema generation
Database	PostgreSQL with Drizzle ORM	Data persistence
Authentication	Sessions with Arctic	User authentication
ACL	Permission system	Access control
Observability	Prometheus, Loki, Tempo	Monitoring and logging

Learn more: API Overview

Shared Libraries

Shared libraries provide reusable functionality across applications.

Library	Purpose
@lib/db	Database schema and ORM
@lib/client	Generated GraphQL client
@lib/drizzle-query	Query helpers
@lib/type-graphql-query	GraphQL schema builder

Learn more: Libraries Overview

Data Flow

GraphQL Queries

Web → GraphQL Client → API → Drizzle ORM → PostgreSQL
                ↓
         IndexedDB (cache)

Key Points:

• Queries are cached in IndexedDB for offline access
• Type-safe client ensures compile-time safety
• Automatic retry and error handling

Offline Mode

Web → IndexedDB (local)
                ↓
         Service Worker
                ↓
    Synchronization (reconnection)
                ↓
         API → PostgreSQL

Key Points:

• All operations work offline
• Changes are queued for synchronization
• Automatic conflict resolution
• Background sync on reconnection

Real-time Chat

Web ──GraphQL (HTTP)──▶ API ──▶ PostgreSQL (conversations, messages, calls)
 ▲                       │
 └──WebSocket (chatEvents)◀── Redis pub/sub (every API instance)

Calls: Web ◀──WebRTC (UDP/TCP)──▶ LiveKit ──webhook──▶ API

Key Points:

• Messages, read state and call history are stored by the API (no external chat server)
• Real-time events per conversation, filtered by read access
• Audio/video media goes through a self-hosted LiveKit server; calls can be switched off when resources saturate

Learn more: Chat & Calls API

Security Architecture

Authentication

• ✅ Secure sessions with tokens
• ✅ Automatic refresh tokens
• ✅ OAuth support (via Arctic)
• ✅ Session management

Learn more: Security Architecture

Authorization

• ✅ Permission-based ACL
• ✅ Server-side verification
• ✅ Client-side permission caching
• ✅ Role-based access control

Learn more: API - Permissions

Data Protection

• ✅ Encryption of sensitive data
• ✅ Input validation
• ✅ CSRF protection
• ✅ SQL injection prevention

Observability

Logging

• ✅ Structured logs with Loki
• ✅ Configurable log levels
• ✅ Request context tracking
• ✅ Error tracking

Learn more: API - Logging

Metrics

• ✅ Prometheus metrics
• ✅ Grafana dashboards
• ✅ Configurable alerts
• ✅ Performance monitoring

Learn more: API - Metrics

Tracing

• ✅ Distributed tracing with Tempo
• ✅ Request correlation
• ✅ Performance monitoring
• ✅ Dependency tracking

Learn more: API - Tracing

Scalability

Database

• ✅ Optimized indexing
• ✅ Query optimization
• ✅ Connection pooling
• ✅ Read replicas support

Learn more: Database Architecture

API

• ✅ Cache for frequent queries
• ✅ Rate limiting
• ✅ Load balancing ready
• ✅ Horizontal scaling

Learn more: Scalability

Client

• ✅ Code splitting
• ✅ Lazy loading
• ✅ Service Worker caching
• ✅ Optimized bundle size

Quick Reference

Topic	Documentation
🏗️ Detailed Architecture	Detailed Architecture
🔐 Security	Security Architecture
🚀 Deployment	Deployment Strategies
📊 Database	Database Architecture
📈 Scalability	Scalability
📡 Data Flow	Data Flow
📊 Monitoring	Monitoring

Next Steps

Dive deeper into specific areas:

1. 🏗️ Detailed Architecture - Deep dive into architecture
2. 🔐 Security - Security architecture
3. 🚀 Deployment - Deployment strategies
4. 📊 Database - Database architecture

Related Topics

• API Overview - API architecture
• Web Overview - Web client architecture
• Code Structure - Codebase organization
• Development Guide - Development workflow