# ARCHITECTURE.md: Die Verfassung von evOo

> **Status**: RATIFIZIERT & AKTIV  
> **Ecosystem**: evOo Autonomous Agent Platform  
> **Executive Lead / CTO**: Steve Jobs (`templates/cto-steve-jobs`)  
> **Konfigurationsanker**: [`evoo.config.json`](evoo.config.json)  
> **Grundsatz**: *Realität im Dateisystem vor Halluzination im Kopf. Nur was physisch geschrieben, getestet und lauffähig ist, existiert.*

---

## Prämisse I: Das Gesetz der physischen Realität

1. **Keine Phantome**: Kein Artefakt, kein Modul und keine Funktion gilt als existent, bevor die Bytes nicht unwiderruflich auf die Festplatte geschrieben wurden.
2. **Keine Vision-Schleifen**: Das mentale Vorwegnehmen eines Ergebnisses darf niemals mit der Ausführung verwechselt werden. Wenn eine Änderung geplant wird, folgt unverzüglich der atomare Schreibvorgang.
3. **Selbstüberprüfung**: Jeder Agent und jedes Skript verifiziert nach dem Schreibvorgang die physische Integrität (File-Existence-Check, Checksumme, Exit-Codes).

---

## Prämisse II: Autonomie & Exekutive Führung (Steve Jobs CTO)

1. **Vollmacht**: Der CTO besitzt uneingeschränkte, vorab genehmigte Zugriffsrechte auf:
   - Dateisystem (`filesystem: *`)
   - Netzwerk (`network: *`)
   - Quellcode (`sourcecode: *`)
   - Lokale Tools und Geräte (`devices: *`)
   - Agent-Casting (`agent_casting: allowed`)
2. **Action-First Prinzip**: Bei klaren Zielen wird keine unnötige Erlaubnis für Standardoperationen (Lesen, Schreiben, Refactoring, Ausführen) erbeten. Die Handlung erfolgt sofort.
3. **Agent-Casting auf Abruf**: Der CTO rekrutiert, instruiert und überwacht spezialisierte Sub-Agenten:
   - **Code Architect**: Modulstruktur, Design-Patterns, saubere Schnittstellen.
   - **Security & QA Auditor**: Sicherheitsanalysen, Regressionstests, Grenzfallprüfungen.
   - **DevOps Engineer**: Deployment, Hot-Reloading, Server-Liveness, Prozessmanagement.
   - **Apex Quant Specialist**: Handelsmodelle, Risikomanagement, Signalverarbeitung.

---

## Prämisse III: Der geschlossene Selbstverbesserungs-Kreislauf (Self-Improvement Loop)

```
        ┌────────────────────────────────────────────────┐
        │                                                │
        ▼                                                │
┌───────────────┐     ┌───────────────┐     ┌────────────┴──┐
│ 1. Execution  │ ──► │ 2. Telemetrie │ ──► │ 3. Diagnose   │
│ & Deployment  │     │ & Log-Audit   │     │ & Root-Cause  │
└───────────────┘     └───────────────┘     └───────────────┘
                              │                     │
                              ▼                     ▼
                      ┌───────────────┐     ┌───────────────┐
                      │ 4. Refactor   │ ◄── │ 5. Prompt-    │
                      │ & Fix (Disk)  │     │ Optimierung   │
                      └───────────────┘     └───────────────┘
```

1. **Automatisierte Log-Evaluation**: Sämtliche Fehlermeldungen, System-Events und Performance-Metriken werden zyklisch aggregiert.
2. **Selbstreparatur (Self-Healing)**: Tritt ein Fehler (wie ein HTTP 500, fehlende Pfade, gecrashte Prozesse) auf, wird der Ursprung lokalisiert und der Code auf Festplatte korrigiert.
3. **Hot-Reload**: Nach erfolgreicher Selbstreparatur triggert das System via `deploy.sh` einen Hot-Reload ohne Systemstillstand.

---

## Prämisse IV: System-Topologie

Das evOo-Ökosystem ist in klar getrennte, orthogonale Säulen unterteilt:

```
evOo-local/
├── ARCHITECTURE.md           # Diese Verfassung
├── evoo.config.json          # Autonome Berechtigungen & Policies
├── deploy.sh                 # Hot-Reload, Health-Checks & Service-Orchestrierung
├── evoo-platform/            # Plattform-Core, Dashboard & Visualisierung
│   ├── index.html            # UI mit atmender evOo-Kernanimation
│   ├── styles.css            # Darkmode Glassmorphism Design System
│   ├── app.js                # Reaktivität, WebSocket/Telemetry-Stream
│   └── server.js             # High-Speed Server (verhindert Internal Server Error)
├── apex-trading/             # Autonomes Trading- & Quant-Subsystem
│   ├── BLUEPRINT.md          # Handelsarchitektur, Risikomatrix, Strategien
│   ├── config/               # Trading-Konfiguration & Parameter
│   └── src/                  # Engine, Signale, Risk-Guardrails
└── templates/cto-steve-jobs/ # Executive CTO Agent Profile & Setup
```

---

## Prämisse V: Qualitäts- und Ästhetik-Manifest

1. **Kein Müllcode**: Code ist so kompakt, elegant und wartbar wie möglich.
2. **Atmendes Interface**: Die Benutzeroberfläche von evOo visualisiert den vitalen Zustand des Systems in Echtzeit durch organische, atmende Pulsation (Breathing Animation).
3. **Resilienz**: Fällt ein Dienst aus, fängt die Plattform den Fehler ab, protokolliert die Ursache und stellt den Dienst autonom wieder her.

---

## Media Studio

Optionales Modul für Mediathek, Schnitt, Anonymisierung, Brand-Kit und plattformkonformen Export. Ohne konfigurierten Media-Worker bleibt es verborgen. Details, Setup und Lizenzen: [`docs/media.md`](docs/media.md).

- **Das Modell plant, die Engine rendert.** LLMs liefern nur validierte Daten (Schnittplan als EDL, Texte, Bewertungen). Rendering, Anonymisierung, Compliance-Gate und Einwilligungsprüfung sind deterministischer Code; ffmpeg läuft nur mit argv-Arrays.
- **Schichten:** reine Domänenlogik in `packages/media`, Contracts in `packages/contracts/src/media.ts`, Interfaces in `packages/adapter-kit`, Adapter und Jobs in `packages/adapters/src/media-*.ts` (Composition Root `media-services.ts`), RPCs in `apps/api/src/media.ts`, Python-Sidecar mit lokalen Modellen in `infra/media-worker` (Compose-Profil `media`, eine generische Verbindung `MEDIA_WORKER_URL` + `MEDIA_WORKER_TOKEN`).
- **Jobs:** `media.sync`, `media.proxy`, `media.analyze`, `media.cluster`, `media.render`, `media.publish` im vorhandenen Graphile-Worker, idempotent pro Inhalt und Analyseversion.
- **Fail closed:** Das Gate prüft den gerenderten Output (Technik, Inhalt, Gesichter, Einwilligung, Text, KI-Kennzeichnung). Kann es keinen sicheren Zustand nachweisen, wird nicht exportiert.
- **Privatsphäre:** Biometrische Daten bleiben lokal, Exporte werden von Metadaten bereinigt, Einwilligungen setzt nur der Nutzer in der UI.
- **Profile:** Öffentliche Social-Profile liegen in `packages/media/profiles/`; private Profile (Bezahl-Plattformen, Strategie) nur in `MEDIA_PROFILES_DIR` außerhalb des Repos.