b0esche_cloud/docs/ARCHITECTURE.md

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

# 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