# AccountForger - Produktionsarchitektur

## Konfiguration

| Aspekt | Entscheidung |
|--------|--------------|
| **Hosting** | Eigener VPS/Root-Server (Docker Compose) |
| **Multi-Tenant** | Ja - mehrere Clients mit eigenen API-Keys |
| **eSIM-Strategie** | Pool mit Rotation (mehrere Nummern pro Kunde) |
| **Router-Standort** | Beim Kunden (dezentral) |
| **eSIM-Verwaltung** | Zentral durch Anbieter |

---

## Business-Modell

```
┌─────────────────────────────────────────────────────────────────┐
│  VERKAUF AN KUNDEN                                              │
│                                                                  │
│  Paket beinhaltet:                                              │
│  ├── Software-Lizenz (AccountForger Desktop)                    │
│  ├── Vorkonfigurierter RUTX11 Router                           │
│  │   ├── Webhook bereits eingerichtet                          │
│  │   ├── Auth-Token basierend auf Lizenz                       │
│  │   └── eSIMs bereits eingelegt                               │
│  └── Telefonnummern im System registriert                      │
│                                                                  │
│  Kunde muss nur:                                                │
│  ├── Router mit Strom + Internet verbinden                     │
│  └── Software installieren + Lizenz aktivieren                 │
└─────────────────────────────────────────────────────────────────┘
```

---

## Übersicht

Dezentrale Router beim Kunden, zentraler Server für Verifikation.

```
┌─────────────────────────────────────────────────────────────────┐
│                         KUNDE A                                  │
│  ┌─────────────────┐              ┌──────────────────┐          │
│  │  Desktop Client │              │  RUTX11 Router   │          │
│  │  (Lizenz: A123) │              │  (Token: A123)   │          │
│  └────────┬────────┘              └────────┬─────────┘          │
└───────────┼────────────────────────────────┼────────────────────┘
            │                                │
┌───────────┼────────────────────────────────┼────────────────────┐
│                         KUNDE B                                  │
│  ┌─────────────────┐              ┌──────────────────┐          │
│  │  Desktop Client │              │  RUTX11 Router   │          │
│  │  (Lizenz: B456) │              │  (Token: B456)   │          │
│  └────────┬────────┘              └────────┬─────────┘          │
└───────────┼────────────────────────────────┼────────────────────┘
            │                                │
            │ HTTPS (API)                    │ HTTPS (Webhook)
            │                                │
            ▼                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    ZENTRALER SERVER (VPS)                       │
│                                                                  │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐ │
│  │ Email       │  │ SMS         │  │ Client/Router           │ │
│  │ Service     │  │ Service     │  │ Registry                │ │
│  │             │  │             │  │                         │ │
│  │ IMAP Polling│  │ Webhook     │  │ Lizenz → Router → Tel.  │ │
│  └─────────────┘  │ Empfänger   │  └─────────────────────────┘ │
│                   └─────────────┘                               │
│                                                                  │
│  PostgreSQL                              FastAPI                │
└─────────────────────────────────────────────────────────────────┘
```

---

## 1. Server-Komponenten

### Technologie-Stack
| Komponente | Technologie |
|------------|-------------|
| Framework | FastAPI (Python) |
| Datenbank | PostgreSQL |
| ORM | SQLAlchemy 2.0 |
| Background Jobs | Celery + Redis |
| Cache | Redis |
| Auth | API-Keys (JWT optional) |

### API-Endpunkte

| Endpunkt | Methode | Beschreibung |
|----------|---------|--------------|
| `/api/v1/verification/email/request` | POST | Email-Adresse anfordern |
| `/api/v1/verification/email/code/{id}` | GET | Email-Code abfragen |
| `/api/v1/verification/sms/request` | POST | Telefonnummer anfordern |
| `/api/v1/verification/sms/code/{id}` | GET | SMS-Code abfragen |
| `/api/v1/webhook/rutx11/sms` | POST | SMS-Webhook vom Router |
| `/api/v1/phone/available` | GET | Verfügbare Nummern |

### Datenbank-Schema

```sql
-- Clients (Lizenznehmer)
CREATE TABLE clients (
    id UUID PRIMARY KEY,
    license_key VARCHAR(50) UNIQUE NOT NULL,
    name VARCHAR(255),
    api_key_hash VARCHAR(255) NOT NULL,
    tier VARCHAR(20) DEFAULT 'standard',
    is_active BOOLEAN DEFAULT true,
    created_at TIMESTAMP DEFAULT NOW()
);

-- Router (dezentral beim Kunden)
CREATE TABLE routers (
    id UUID PRIMARY KEY,
    client_id UUID NOT NULL REFERENCES clients(id),
    router_token VARCHAR(100) UNIQUE NOT NULL,  -- = Lizenzschlüssel oder abgeleitet
    model VARCHAR(50) DEFAULT 'RUTX11',
    serial_number VARCHAR(100),
    is_online BOOLEAN DEFAULT false,
    last_seen_at TIMESTAMP,
    created_at TIMESTAMP DEFAULT NOW()
);

-- Telefonnummern (pro Router/Kunde)
CREATE TABLE phone_numbers (
    id UUID PRIMARY KEY,
    router_id UUID NOT NULL REFERENCES routers(id),
    phone_number VARCHAR(20) UNIQUE NOT NULL,
    esim_slot INTEGER NOT NULL,  -- 1 oder 2
    carrier VARCHAR(100),
    is_active BOOLEAN DEFAULT true,
    cooldown_until TIMESTAMP,
    usage_count INTEGER DEFAULT 0,
    last_used_at TIMESTAMP
);

-- Verifikations-Anfragen
CREATE TABLE verification_requests (
    id UUID PRIMARY KEY,
    client_id UUID NOT NULL REFERENCES clients(id),
    platform VARCHAR(50) NOT NULL,
    verification_type VARCHAR(20) NOT NULL,  -- 'email' / 'sms'
    email_address VARCHAR(255),
    phone_number_id UUID REFERENCES phone_numbers(id),
    status VARCHAR(20) DEFAULT 'pending',
    verification_code VARCHAR(20),
    created_at TIMESTAMP DEFAULT NOW(),
    expires_at TIMESTAMP
);

-- Email-Konten (zentral Server-verwaltet)
CREATE TABLE email_accounts (
    id UUID PRIMARY KEY,
    email_address VARCHAR(255) UNIQUE NOT NULL,
    imap_server VARCHAR(255) NOT NULL,
    imap_port INTEGER DEFAULT 993,
    password_encrypted BYTEA NOT NULL,
    domain VARCHAR(255) NOT NULL,
    is_active BOOLEAN DEFAULT true
);

-- Empfangene SMS
CREATE TABLE sms_messages (
    id UUID PRIMARY KEY,
    router_id UUID NOT NULL REFERENCES routers(id),
    phone_number VARCHAR(20) NOT NULL,
    sender VARCHAR(50),
    message_body TEXT NOT NULL,
    received_at TIMESTAMP DEFAULT NOW(),
    processed BOOLEAN DEFAULT false,
    matched_request_id UUID REFERENCES verification_requests(id)
);
```

### Entity-Relationship

```
clients (1) ──────< routers (1) ──────< phone_numbers (n)
    │                  │
    │                  └──────< sms_messages (n)
    │
    └──────< verification_requests (n)
```

### Server-Projektstruktur

```
accountforger-server/
├── app/
│   ├── main.py                 # FastAPI Entry
│   ├── config.py               # Konfiguration
│   ├── api/v1/
│   │   ├── verification.py     # Verifikations-Endpunkte
│   │   ├── webhooks.py         # RUTX11 Webhook
│   │   └── auth.py             # Authentifizierung
│   ├── services/
│   │   ├── email_service.py    # IMAP-Polling
│   │   ├── sms_service.py      # SMS-Verarbeitung
│   │   └── phone_rotation.py   # eSIM-Rotation
│   └── infrastructure/
│       ├── database.py
│       └── imap_client.py
├── docker-compose.yml
└── requirements.txt
```

---

## 2. RUTX11 Integration

### SMS-Forwarding Konfiguration

1. **Im RUTX11 WebUI:**
   - Services → Mobile Utilities → SMS Gateway → SMS Forwarding
   - Neue Regel: HTTP POST an `https://server.domain/api/v1/webhook/rutx11/sms`

2. **Webhook-Payload vom Router:**
```json
{
  "sender": "+49123456789",
  "message": "123456 is your verification code",
  "timestamp": "2026-01-17T10:30:00Z",
  "sim_slot": 1
}
```

### Dezentrale Router-Architektur

```
                    ┌─────────────────────────────────┐
                    │      Verification Server        │
                    │                                 │
                    │  ┌─────────────────────────┐   │
                    │  │   Router Registry       │   │
                    │  │                         │   │
                    │  │  - Client ↔ Router Map  │   │
                    │  │  - Telefonnummern/Client│   │
                    │  │  - Health Monitoring    │   │
                    │  └───────────┬─────────────┘   │
                    └──────────────┼─────────────────┘
                                   │
              ┌────────────────────┼────────────────────┐
              │                    │                    │
              ▼                    ▼                    ▼
     ┌────────────────┐   ┌────────────────┐   ┌────────────────┐
     │ Kunde A Router │   │ Kunde B Router │   │ Kunde C Router │
     │ Token: A123    │   │ Token: B456    │   │ Token: C789    │
     │ Tel: +49...    │   │ Tel: +49...    │   │ Tel: +49...    │
     └────────────────┘   └────────────────┘   └────────────────┘
           │                    │                    │
           └────────────────────┴────────────────────┘
                                │
                    Webhooks an zentralen Server
```

### Router-Vorkonfiguration (vor Versand)

```bash
# RUTX11 SMS Forwarding Konfiguration
# Services → Mobile Utilities → SMS Gateway → SMS Forwarding

Webhook URL:    https://verify.domain.com/api/v1/webhook/sms
HTTP Method:    POST
Headers:        X-Router-Token: {LIZENZ_TOKEN}
Payload Format: JSON
```

### eSIM-Rotationsstrategie

| Strategie | Beschreibung |
|-----------|--------------|
| Cooldown | 30 Min. Pause nach Nutzung pro Nummer |
| Round Robin | Abwechselnd durch alle verfügbaren Nummern |
| Platform-Aware | Tracken welche Nummer für welche Platform verwendet wurde |
| Load Balancing | Gleichmäßige Verteilung über alle Router/SIM-Banks |
| Health Check | Automatische Deaktivierung bei Problemen |

---

## 3. Client-Änderungen

### Was bleibt im Client
- PyQt5 UI
- Playwright Browser-Automation
- Fingerprint-Management
- Lokale SQLite-Datenbank

### Was entfernt wird
- `utils/email_handler.py` → ersetzt durch API-Calls
- `config/email_config.json` → keine Credentials mehr im Client
- Hardcoded `"123456"` SMS-Placeholder

### Neuer VerificationClient

**Datei:** `utils/verification_client.py`

```python
class VerificationClient:
    def __init__(self, server_url: str, api_key: str):
        self.server_url = server_url
        self.api_key = api_key

    def request_email(self, platform: str) -> dict:
        """Fordert Email-Adresse vom Server an."""
        response = requests.post(
            f"{self.server_url}/api/v1/verification/email/request",
            json={"platform": platform},
            headers={"X-API-Key": self.api_key}
        )
        return response.json()  # {"request_id": "...", "email_address": "..."}

    def request_sms(self, platform: str) -> dict:
        """Fordert Telefonnummer vom Server an."""
        response = requests.post(
            f"{self.server_url}/api/v1/verification/sms/request",
            json={"platform": platform},
            headers={"X-API-Key": self.api_key}
        )
        return response.json()  # {"request_id": "...", "phone_number": "..."}

    def poll_for_code(self, request_id: str, type: str, timeout: int = 120) -> str:
        """Pollt Server bis Code empfangen wurde."""
        # ...
```

### Zu ändernde Dateien

| Datei | Änderung |
|-------|----------|
| `social_networks/base_automation.py` | `verification_client` Parameter hinzufügen |
| `social_networks/*/verification.py` | API-Calls statt direktem IMAP |
| `controllers/platform_controllers/base_worker_thread.py` | VerificationClient initialisieren |
| `config/server_config.json` (NEU) | Server-URL und API-Key |

---

## 4. Multi-Tenant Architektur

### Client-Verwaltung

```sql
-- Clients (Tenants)
CREATE TABLE clients (
    id UUID PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    license_key VARCHAR(50) UNIQUE NOT NULL,
    api_key_hash VARCHAR(255) NOT NULL,
    is_active BOOLEAN DEFAULT true,
    tier VARCHAR(20) DEFAULT 'standard',  -- standard, premium, enterprise
    created_at TIMESTAMP DEFAULT NOW()
);

-- Rate Limits pro Tier
CREATE TABLE tier_limits (
    tier VARCHAR(20) PRIMARY KEY,
    email_requests_per_hour INTEGER,
    sms_requests_per_hour INTEGER,
    max_concurrent_verifications INTEGER
);

INSERT INTO tier_limits VALUES
    ('standard', 50, 20, 5),
    ('premium', 200, 100, 20),
    ('enterprise', 1000, 500, 100);
```

### Tenant-Isolation

| Aspekt | Implementierung |
|--------|-----------------|
| API-Keys | Eindeutig pro Client |
| Rate Limits | Per-Tenant basierend auf Tier |
| Logging | Client-ID in allen Logs |
| Ressourcen | Shared Pool mit Fair-Use |
| Abrechnung | Usage-Tracking pro Client |

---

## 5. Sicherheit

### Authentifizierung
- API-Key pro Client-Installation
- Gehashed in Server-DB (bcrypt)
- Gebunden an Lizenzschlüssel

### Credentials-Management
| Credential | Speicherort | Schutz |
|------------|-------------|--------|
| IMAP-Passwörter | Server DB | AES-256 verschlüsselt |
| API-Keys | Server DB | bcrypt Hash |
| RUTX11 Webhook | Server .env | Umgebungsvariable |
| Client API-Key | Client Config | Verschlüsselt lokal |

### Netzwerk
- HTTPS-Only (TLS 1.3)
- IP-Whitelist für RUTX11 Webhook
- Rate Limiting (10 Email-Requests/Min, 5 SMS-Requests/Min)

---

## 6. Deployment

### Docker Compose (empfohlen)

```yaml
version: '3.8'
services:
  api:
    build: .
    ports:
      - "8000:8000"
    environment:
      - DATABASE_URL=postgresql://user:pass@db:5432/verify
      - REDIS_URL=redis://redis:6379
    depends_on:
      - db
      - redis

  db:
    image: postgres:15
    volumes:
      - pgdata:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine

  celery:
    build: .
    command: celery -A app.worker worker -l info
```

---

## 7. Verifikation / Testing

1. **Server starten:** `docker-compose up`
2. **Email-Test:**
   - POST `/api/v1/verification/email/request` mit `{"platform": "instagram"}`
   - GET `/api/v1/verification/email/code/{id}` → Code erhalten
3. **SMS-Test:**
   - Webhook simulieren: POST an `/api/v1/webhook/rutx11/sms`
   - Prüfen ob SMS in DB landet und Request gematcht wird
4. **Client-Integration:**
   - `VerificationClient` instanziieren
   - Account-Erstellung mit Server-Verifikation testen

---

## 8. Onboarding-Prozess (Neuer Kunde)

### Admin-Workflow

```
1. Neue Lizenz generieren
   └── license_key: "AF-2026-XXXXX"

2. Client in DB anlegen
   └── INSERT INTO clients (license_key, name, api_key_hash, tier)

3. Router vorkonfigurieren
   ├── RUTX11 Webhook URL setzen
   ├── X-Router-Token Header = license_key
   └── eSIMs einlegen

4. Telefonnummern registrieren
   ├── INSERT INTO routers (client_id, router_token)
   └── INSERT INTO phone_numbers (router_id, phone_number, esim_slot)

5. Paket versenden
   ├── Router (Plug & Play ready)
   └── Software-Download Link + Lizenzschlüssel
```

### Kunde-Workflow

```
1. Router auspacken und anschließen
   └── Strom + Ethernet/WLAN

2. Software installieren
   └── AccountForger.exe

3. Lizenz aktivieren
   └── Lizenzschlüssel eingeben → Server validiert

4. Fertig!
   └── SMS-Verifikation funktioniert automatisch
```

---

## 9. Implementierungsreihenfolge

1. **Server Basis** - FastAPI Setup, DB-Schema, Email-Service
2. **Router Registry** - Client/Router/Telefonnummer Verwaltung
3. **RUTX11 Webhook** - SMS empfangen, Router-Token validieren, Request matchen
4. **Client Integration** - VerificationClient implementieren
5. **Plattform-Migration** - Alle verification.py Dateien umstellen
6. **Admin-Panel** - Kunden/Router/Nummern verwalten (optional)
7. **Security & Monitoring** - Rate Limiting, Logging, Health Checks