# b0esche.cloud Architecture ## System Overview b0esche.cloud is a self-hosted cloud storage platform inspired by Google Workspace, built with a modern microservices-style architecture. ## High-Level Architecture ``` ┌─────────────────────────────────────┐ │ Internet │ └─────────────────┬───────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────────────────────────┐ │ Traefik Reverse Proxy │ │ (SSL Termination, Routing, Load Balancing) │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ www.* │ │ go.* │ │ storage.* │ │ of.* │ │ │ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │ └─────────┼────────────────┼────────────────┼────────────────┼────────────────────────┘ │ │ │ │ ▼ ▼ ▼ ▼ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ Flutter Web │ │ Go Backend │ │ Nextcloud │ │ Collabora │ │ (Nginx) │ │ (API) │ │ (Storage) │ │ (Office) │ └──────────────┘ └──────┬───────┘ └──────────────┘ └──────────────┘ │ ▼ ┌──────────────┐ │ PostgreSQL │ │ (Database) │ └──────────────┘ ``` ## Components ### 1. Flutter Web Frontend (`b0esche_cloud/`) The user-facing web application built with Flutter. **Technology Stack:** - Flutter 3.x with Dart - BLoC pattern for state management - Material Design 3 theming **Key Modules:** | Module | Purpose | |--------|---------| | `blocs/` | Business logic components (auth, files, orgs) | | `models/` | Data models (User, File, Organization) | | `pages/` | UI screens (Home, Files, Settings, Admin) | | `repositories/` | Data access layer | | `services/` | API client, WebAuthn service | | `widgets/` | Reusable UI components | **State Management Flow:** ``` User Action → BLoC Event → BLoC Logic → State Update → UI Rebuild ↓ Repository ↓ API Service ↓ Go Backend ``` ### 2. Go Backend (`go_cloud/`) The API server handling business logic, authentication, and service orchestration. **Technology Stack:** - Go 1.21+ - Chi Router for HTTP routing - sqlx for database access - go-webauthn for passkey authentication **Key Packages:** | Package | Purpose | |---------|---------| | `internal/auth/` | Authentication (OIDC, Passkeys, Sessions) | | `internal/files/` | File metadata and operations | | `internal/org/` | Organization and membership management | | `internal/storage/` | Nextcloud/WebDAV integration | | `internal/http/` | HTTP handlers and WOPI endpoints | | `internal/middleware/` | Auth, logging, CORS middleware | | `pkg/jwt/` | JWT token utilities | **Request Flow:** ``` HTTP Request → Traefik → Chi Router → Middleware → Handler → Service → Response ↓ Database/Storage ``` ### 3. PostgreSQL Database Stores application metadata (not files). **Key Tables:** - `users` - User accounts and profiles - `roles` - Permission roles (user, admin, superadmin) - `passkeys` - WebAuthn credentials - `organizations` - Org definitions - `org_memberships` - User-org relationships - `activities` - Audit log **Schema Relationships:** ``` users ──┬── passkeys (1:N) ├── org_memberships (N:M) ── organizations ├── recovery_codes (1:N) └── activities (1:N) ``` ### 4. Nextcloud (Storage) File storage backend and OIDC provider. **Responsibilities:** - File storage via WebDAV - User authentication (OIDC) - File sharing capabilities - Version control **Integration Points:** - WebDAV API for file operations - OIDC for authentication - User provisioning sync ### 5. Collabora Online (Office) Document editing service for Office files. **Supported Formats:** - Documents: DOCX, ODT, RTF - Spreadsheets: XLSX, ODS, CSV - Presentations: PPTX, ODP **Integration:** - WOPI protocol for document access - Embedded iframe in Flutter app ### 6. Traefik (Reverse Proxy) SSL termination and request routing. **Features:** - Automatic SSL via Let's Encrypt (DNS-01 challenge) - Dynamic service discovery - Load balancing - Request routing based on hostname ## Data Flow ### Authentication Flow ``` ┌────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ Client │───▶│ Frontend │───▶│ Backend │───▶│ Database │ └────────┘ └──────────┘ └──────────┘ └──────────┘ │ │ │ 1. Username + Passkey │ │─────────────────────────────▶│ │ │ │ 2. WebAuthn Challenge │ │◀─────────────────────────────│ │ │ │ 3. Signed Challenge │ │─────────────────────────────▶│ │ │ 4. Verify Signature │ │ 5. Create Session │ 6. JWT Token │ │◀─────────────────────────────│ ``` ## Security Architecture ### Authentication & Authorization - **Passkeys (WebAuthn)**: Primary authentication method using FIDO2/U2F security keys - **JWT Tokens**: Session-based tokens with configurable expiration - **Role-Based Access Control (RBAC)**: Owner, Admin, Member roles for organizations - **Permission System**: Granular permissions for file operations (read, write, view, edit) ### Input Validation & Sanitization - **Path Traversal Protection**: All file paths are sanitized to prevent directory traversal attacks - **UUID Validation**: All resource IDs (users, orgs, files) are validated as proper UUIDs - **JSON Schema Validation**: API inputs are validated for correct structure and types ### Network Security - **HTTPS Only**: All external traffic is encrypted via TLS - **CORS Policy**: Restricted to allowed origins with credentials support - **Rate Limiting**: 100 requests/minute general, 10 requests/minute for auth endpoints - **Security Headers**: - `X-Content-Type-Options: nosniff` - `X-Frame-Options: DENY` (except for WOPI/Collabora) - `X-XSS-Protection: 1; mode=block` - `Content-Security-Policy`: Restrictive policy allowing only necessary sources - `Referrer-Policy: strict-origin-when-cross-origin` ### Data Protection - **Encrypted Storage**: Files stored encrypted in Nextcloud - **Secure Passwords**: Auto-generated secure passwords for Nextcloud user accounts - **Audit Logging**: All operations logged with user/org context - **No Secrets in Logs**: Sensitive data never logged ### API Security - **Token Validation**: Every protected endpoint validates JWT tokens - **Session Management**: Secure session handling with database-backed validation - **Error Handling**: Safe error responses that don't leak internal details ### File Security - **Scoped Access**: Users can only access files within their personal workspace or authorized organizations - **Share Tokens**: Public shares use short-lived, single-use tokens - **Nextcloud Integration**: Leverages Nextcloud's security features for file access ### Infrastructure Security - **Container Security**: Docker images run as non-root where possible - **Network Isolation**: Internal Docker networks prevent direct external access - **Deployment Security**: Automated deployments with health checks ## Data Flow ### File Upload Flow ``` ┌────────┐ ┌──────────┐ ┌──────────┐ ┌───────────┐ │ Client │───▶│ Frontend │───▶│ Backend │───▶│ Nextcloud │ └────────┘ └──────────┘ └──────────┘ └───────────┘ │ │ │ │ 1. Select File │ │ │─────────────────────────────▶│ │ │ │ │ │ │ 2. WebDAV PUT │ │ │───────────────▶│ │ │ │ │ │ 3. Success │ │ │◀───────────────│ │ │ │ │ │ 4. Save Metadata │ │ (PostgreSQL) │ │ 5. Confirmation │ │ │◀─────────────────────────────│ │ ``` ## Network Architecture ### Docker Networks ``` ┌─────────────────────────────────────────────────────────────┐ │ proxy (172.20.0.0/16) │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │ traefik │ │ flutter │ │ go │ │nextcloud│ │ │ │ │ │ web │ │ backend │ │ │ │ │ └─────────┘ └─────────┘ └────┬────┘ └─────────┘ │ └───────────────────────────────┼─────────────────────────────┘ │ ┌───────────────────────────────┼─────────────────────────────┐ │ backend (internal) │ │ ┌────┴────┐ │ │ │postgres │ │ │ └─────────┘ │ └─────────────────────────────────────────────────────────────┘ ``` ### Port Mapping | Service | Internal Port | External | |---------|---------------|----------| | Traefik | 80, 443 | Exposed | | Flutter Web | 80 | Via Traefik | | Go Backend | 8080 | Via Traefik | | PostgreSQL | 5432 | Internal only | | Nextcloud | 80 | Via Traefik | | Collabora | 9980 | Via Traefik | ## Security Architecture ### Authentication Layers 1. **Primary**: WebAuthn Passkeys (FIDO2) 2. **Fallback**: Optional password authentication 3. **Legacy**: OIDC via Nextcloud (deprecated) 4. **Recovery**: One-time recovery codes ### Authorization Model ``` ┌─────────────────────────────────────────────────────────────┐ │ Role Hierarchy │ │ │ │ superadmin (Level 3) │ │ ├── All system access │ │ ├── User management │ │ └── Can manage admins │ │ │ │ │ ▼ │ │ admin (Level 2) │ │ ├── Organization management │ │ ├── User role management (within orgs) │ │ └── Activity monitoring │ │ │ │ │ ▼ │ │ user (Level 1) │ │ ├── Personal file management │ │ ├── Organization membership │ │ └── Basic settings │ └─────────────────────────────────────────────────────────────┘ ``` ### Organization Roles Within each organization: - **Owner**: Full control, can delete org - **Admin**: Can manage members and files - **Member**: Read/write access to shared files ## Scalability Considerations ### Current Architecture (Single Server) - All services on one VPS - Suitable for small teams (< 100 users) - Simple deployment and maintenance ### Future Scaling Options 1. **Database**: Read replicas, connection pooling 2. **Storage**: S3-compatible backends, CDN for static assets 3. **Backend**: Horizontal scaling with load balancer 4. **Frontend**: CDN distribution, edge caching ## Monitoring & Observability ### Logging - **Traefik**: Access logs, error logs - **Go Backend**: Structured JSON logs - **PostgreSQL**: Query logs, slow query analysis - **Docker**: Container logs via `docker logs` ### Health Checks ```bash # Backend health curl https://go.b0esche.cloud/health # Frontend availability curl -I https://www.b0esche.cloud # Database connectivity docker exec go-postgres pg_isready ``` ### Metrics (Future) - Prometheus for metrics collection - Grafana for visualization - AlertManager for alerting