breakpilot-pwa/docs/architecture/environments.md

# Umgebungs-Architektur

## Übersicht

BreakPilot verwendet eine 3-Umgebungs-Strategie für sichere Entwicklung und Deployment:

```
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Development   │────▶│     Staging     │────▶│   Production    │
│   (develop)     │     │    (staging)    │     │     (main)      │
└─────────────────┘     └─────────────────┘     └─────────────────┘
     Tägliche            Getesteter Code         Produktionsreif
     Entwicklung
```

## Umgebungen

### Development (Dev)

**Zweck:** Tägliche Entwicklungsarbeit

| Eigenschaft | Wert |
|-------------|------|
| Git Branch | `develop` |
| Compose File | `docker-compose.yml` + `docker-compose.override.yml` (auto) |
| Env File | `.env.dev` |
| Database | `breakpilot_dev` |
| Debug | Aktiviert |
| Hot-Reload | Aktiviert |

**Start:**
```bash
./scripts/start.sh dev
# oder einfach:
docker compose up -d
```

### Staging

**Zweck:** Getesteter, freigegebener Code vor Produktion

| Eigenschaft | Wert |
|-------------|------|
| Git Branch | `staging` |
| Compose File | `docker-compose.yml` + `docker-compose.staging.yml` |
| Env File | `.env.staging` |
| Database | `breakpilot_staging` (separates Volume) |
| Debug | Deaktiviert |
| Hot-Reload | Deaktiviert |

**Start:**
```bash
./scripts/start.sh staging
# oder:
docker compose -f docker-compose.yml -f docker-compose.staging.yml up -d
```

### Production (Prod)

**Zweck:** Live-System für Endbenutzer (ab Launch)

| Eigenschaft | Wert |
|-------------|------|
| Git Branch | `main` |
| Compose File | `docker-compose.yml` + `docker-compose.prod.yml` |
| Env File | `.env.prod` (NICHT im Repository!) |
| Database | `breakpilot_prod` (separates Volume) |
| Debug | Deaktiviert |
| Vault | Pflicht (keine Env-Fallbacks) |

## Datenbank-Trennung

Jede Umgebung verwendet separate Docker Volumes für vollständige Datenisolierung:

```
┌─────────────────────────────────────────────────────────────┐
│                    PostgreSQL Volumes                        │
├─────────────────────────────────────────────────────────────┤
│  breakpilot-dev_postgres_data      │ Development Database   │
│  breakpilot_staging_postgres       │ Staging Database       │
│  breakpilot_prod_postgres          │ Production Database    │
└─────────────────────────────────────────────────────────────┘
```

## Port-Mapping

Um mehrere Umgebungen gleichzeitig laufen zu lassen, verwenden sie unterschiedliche Ports:

| Service | Dev Port | Staging Port | Prod Port |
|---------|----------|--------------|-----------|
| Backend | 8000 | 8001 | 8000 |
| PostgreSQL | 5432 | 5433 | - (intern) |
| MinIO | 9000/9001 | 9002/9003 | - (intern) |
| Qdrant | 6333/6334 | 6335/6336 | - (intern) |
| Mailpit | 8025/1025 | 8026/1026 | - (deaktiviert) |

## Git Branching Strategie

```
main (Prod)     ← Nur Release-Merges, geschützt
    │
    ▼
staging         ← Getesteter Code, Review erforderlich
    │
    ▼
develop (Dev)   ← Tägliche Arbeit, Default-Branch
    │
    ▼
feature/*       ← Feature-Branches (optional)
```

### Workflow

1. **Entwicklung:** Arbeite auf `develop`
2. **Code-Review:** Erstelle PR von Feature-Branch → `develop`
3. **Staging:** Promote `develop` → `staging` mit Tests
4. **Release:** Promote `staging` → `main` nach Freigabe

### Promotion-Befehle

```bash
# develop → staging
./scripts/promote.sh dev-to-staging

# staging → main (Production)
./scripts/promote.sh staging-to-prod
```

## Secrets Management

### Development
- `.env.dev` enthält Entwicklungs-Credentials
- Vault optional (Dev-Token)
- Mailpit für E-Mail-Tests

### Staging
- `.env.staging` enthält Test-Credentials
- Vault empfohlen
- Mailpit für E-Mail-Sicherheit

### Production
- `.env.prod` NICHT im Repository
- Vault PFLICHT
- Echte SMTP-Konfiguration

Siehe auch: [secrets-management.md](./secrets-management.md)

## Docker Compose Architektur

```
docker-compose.yml              ← Basis-Konfiguration
        │
        ├── docker-compose.override.yml  ← Dev (auto-geladen)
        │
        ├── docker-compose.staging.yml   ← Staging (explizit)
        │
        └── docker-compose.prod.yml      ← Production (explizit)
```

### Automatisches Laden

Docker Compose lädt automatisch:
1. `docker-compose.yml`
2. `docker-compose.override.yml` (falls vorhanden)

Daher startet `docker compose up` automatisch die Dev-Umgebung.

## Helper Scripts

| Script | Beschreibung |
|--------|--------------|
| `scripts/env-switch.sh` | Wechselt zwischen Umgebungen |
| `scripts/start.sh` | Startet Services für Umgebung |
| `scripts/stop.sh` | Stoppt Services |
| `scripts/promote.sh` | Promotet Code zwischen Branches |
| `scripts/status.sh` | Zeigt aktuellen Status |

## Verifikation

Nach Setup prüfen:

```bash
# Status anzeigen
./scripts/status.sh

# Branches prüfen
git branch -v

# Volumes prüfen
docker volume ls | grep breakpilot
```

## Verwandte Dokumentation

- [secrets-management.md](./secrets-management.md) - Vault & Secrets
- [devsecops.md](./devsecops.md) - CI/CD & Security
- [system-architecture.md](./system-architecture.md) - Gesamtarchitektur