# 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