314 lines
14 KiB
Markdown
314 lines
14 KiB
Markdown
# 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 │
|
|
│◀─────────────────────────────│
|
|
```
|
|
|
|
### 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
|