14 KiB
14 KiB
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 profilesroles- Permission roles (user, admin, superadmin)passkeys- WebAuthn credentialsorganizations- Org definitionsorg_memberships- User-org relationshipsactivities- 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 │
│◀─────────────────────────────│
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
- Primary: WebAuthn Passkeys (FIDO2)
- Fallback: Optional password authentication
- Legacy: OIDC via Nextcloud (deprecated)
- 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
- Database: Read replicas, connection pooling
- Storage: S3-compatible backends, CDN for static assets
- Backend: Horizontal scaling with load balancer
- 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