# 🧩 Komponenten-Standardstruktur

## 1. Ziel
Dieses Dokument beschreibt die einheitliche interne Struktur, den Lebenszyklus und die Schnittstellen aller Programme, Module und Komponenten im KI-Cluster.  
Ziel ist, dass jede Komponente – ob Router, API-Server, Agent, Speicher oder Tool – nach demselben Aufbau funktioniert und sich konsistent starten, erweitern und warten lässt.

---

## 2. Grundprinzip

Jede Komponente ist ein eigenständiges, klar abgegrenztes Modul.  
Eine Komponente kann:
- Aufgaben empfangen (z. B. vom Router oder über eine API),
- eigene Logik ausführen (lokal oder verteilt),
- Ergebnisse speichern oder weiterleiten,
- und Statusinformationen melden.

Diese Struktur erlaubt, dass alle Module untereinander austauschbar bleiben und dennoch einheitlich funktionieren.

---

## 3. Standardverzeichnisstruktur

```plaintext
/<Komponentenname>/
│
├── Planung/
│   ├── Architektur.md
│   ├── Funktionsbeschreibung.md
│   └── Kommunikationsschnittstellen.md
│
├── Entworfener_Code/
│   ├── start.py
│   ├── config.yaml
│   ├── src/
│   │   ├── core.py
│   │   ├── logic.py
│   │   ├── api_connector.py
│   │   └── storage.py
│   ├── tests/
│   │   └── test_core.py
│   └── README.md
│
└── README.md
```

---

## 4. Klassenaufbau

Jede Komponente kann, falls objektorientiert entwickelt, auf einer einheitlichen Basisklasse aufbauen, um Grundfunktionen wie Logging, Config-Handling und Kommunikation gemeinsam zu nutzen.

```python
# Datei: src/core.py

from utils.api_client import APIClient
from utils.memory_connector import Memory
from utils.logging_setup import get_logger

class BaseComponent:
    """Abstrakte Basisklasse für alle Komponenten des KI-Clusters."""

    def __init__(self, name: str):
        self.name = name
        self.api = APIClient()
        self.memory = Memory()
        self.logger = get_logger(name)

    def register(self):
        """Registriert die Komponente beim Router oder Systembus."""
        self.logger.info(f"{self.name} registriert sich beim System.")
        self.api.register_component(self.name)

    def start(self):
        raise NotImplementedError("Jede Komponente muss eine start()-Methode implementieren.")
```

Beispiel für eine spezialisierte Komponente:

```python
# Beispiel: Router-Modul

from src.core import BaseComponent

class RouterModule(BaseComponent):
    """Koordiniert Aufgaben zwischen Komponenten und verteilt Anfragen."""

    def start(self):
        self.logger.info("Router gestartet.")
        self.listen_for_tasks()

    def listen_for_tasks(self):
        # Beispielhafte Implementierung
        self.logger.info("Warte auf eingehende Aufgaben...")
```

---

## 5. Lebenszyklus einer Komponente

| Phase | Beschreibung |
|--------|---------------|
| **Initialisierung** | `start.py` lädt Konfiguration, Logging und die `src/core.py`-Klasse. |
| **Registrierung** | Komponente meldet sich beim Router oder globalen System an. |
| **Ausführung** | Logik läuft (z. B. Verarbeitung, API-Handling, Kommunikation). |
| **Feedback** | Ergebnisse oder Status werden an zentrale Systeme übermittelt. |
| **Beendigung** | Logs und Speicherzustände werden gesichert, Prozesse sauber beendet. |

---

## 6. Konfigurationsdatei (`config.yaml`)

Beispiel:

```yaml
component:
  name: "RouterModule"
  type: "Systemkomponente"
  version: "1.0"

communication:
  router_endpoint: "http://localhost:5000"
  memory_endpoint: "http://localhost:6000"

logging:
  level: "INFO"
  file: "logs/router_module.log"
```

---

## 7. Gemeinsame Schnittstellen

| Schnittstelle | Zweck | Implementierung |
|----------------|--------|------------------|
| **APIClient** | Kommunikation zwischen Komponenten | `utils/api_client.py` |
| **Memory** | Zugriff auf Wissensspeicher | `utils/memory_connector.py` |
| **Logger** | Zentrales Logging-System | `utils/logging_setup.py` |
| **Config Loader** | Einheitliche YAML-Konfiguration | `utils/config_loader.py` |

---

## 8. Kommunikation zwischen Komponenten

Jede Komponente unterstützt mindestens folgende Methoden:

| Methode | Beschreibung |
|----------|---------------|
| `register()` | Meldet sich beim zentralen System an |
| `start()` | Startet die Logik der Komponente |
| `receive_message(data: dict)` | Empfängt Nachrichten oder Aufgaben |
| `send_message(data: dict)` | Sendet Ergebnisse oder Events |
| `shutdown()` | Fährt die Komponente kontrolliert herunter |

---

## 9. Anforderungen an neue Komponenten

Neue Komponenten müssen:
1. von `BaseComponent` erben (falls OOP),
2. in `start.py` eingetragen werden,
3. ihre Konfiguration in `config.yaml` speichern,
4. Unit-Tests unter `/tests/` bereitstellen,
5. und saubere Logging- sowie Feedback-Mechanismen besitzen.

---

## 10. Beispielkommunikation

```python
# Beispiel: Router sendet Aufgabe an API-Modul

task = {
    "type": "fetch_data",
    "parameters": {"url": "https://example.com/api"}
}

api_module.receive_message(task)
```

Die Komponente führt die Aufgabe aus und antwortet:

```python
result = {
    "status": "success",
    "data": {"records": 24}
}
api_module.send_message(result)
```

---

## 11. Zusammenfassung

Alle Komponenten im System folgen diesem Grundschema.  
Dadurch wird erreicht, dass:
- der Router alle Programme gleich ansprechen kann,
- der Builder-Agent neue Komponenten automatisch integrieren kann,
- und das gesamte System modular, testbar und erweiterbar bleibt.

---
© 2025 – KI-Cluster Homelab Architektur  
Autor: *[Dein Name oder Alias]*


### 3.1 Variante: FastAPI-Web-API-Komponente (empfohlen)

Diese Variante verankert die lauffähige Grundstruktur für API-basierte Komponenten mit FastAPI, Logging und Tests.

```plaintext
/<Komponentenname>/
│
├── Planung/
│   ├── Architektur.md
│   ├── Funktionsbeschreibung.md
│   └── Kommunikationsschnittstellen.md
│
├── Entworfener_Code/
│   ├── start.py
│   ├── requirements.txt
│   ├── README.md
│   ├── Dockerfile
│   ├── docker-compose.yml
│   ├── app/
│   │   └── main.py
│   ├── api/
│   │   ├── __init__.py
│   │   ├── router.py
│   │   └── routes/
│   │       ├── __init__.py
│   │       └── execute.py
│   ├── core/
│   │   └── base_component.py
│   ├── config/
│   │   ├── config.yaml
│   │   └── logging.yaml
│   └── tests/
│       └── test_smoke.py
│
└── README.md
```

Pflichten dieser Struktur:
- start.py: lädt Konfiguration (config/config.yaml), initialisiert Logging (config/logging.yaml) und startet den FastAPI-Server (uvicorn, optional Factory/Reload).
- app/main.py: erzeugt die FastAPI-App (create_app), bindet CORS und registriert Router.
- api/router.py und api/routes/execute.py: Beispiel-Routenstruktur inkl. POST /api/execute sowie GET /health.
- core/base_component.py: Basisklasse mit Schnittstelle register() und start() für spätere Komponenten.
- config/logging.yaml: Rotierende Logs (TimedRotatingFileHandler) und zentrale Logger (uvicorn, root).
- tests/test_smoke.py: pytest-Smoketests für Health-Endpoint und /api/execute.
- requirements.txt: Abhängigkeiten (u. a. fastapi, uvicorn, pyyaml, pytest, httpx).
- Dockerfile, docker-compose.yml: Containerisierter Betrieb, Port 8000, Mounts für config/logs.
- Namens-/Code-Style: snake_case, vollständige Typannotationen, Docstrings gemäß Richtlinien.

Hinweis: Diese Variante ergänzt die allgemeine Standardstruktur aus Abschnitt 3 für API-orientierte Komponenten und dient als verbindlicher Grundstock, auf dem spätere Erweiterungen aufbauen.


## 12. Laufzeit-Zielsetzung und Start-Events

- Das Laufzeitprogramm `start.py` bleibt dauerhaft aktiv, da es einen Webserver offen hält und Anfragen entgegennimmt.
- Der Code ist so vorzubereiten, dass bei eingehenden Start-Events (z. B. POST /start) ein Start-Prozess ausgelöst werden kann.
- Mehrere Start-Events dürfen möglich sein. Die Entscheidung, ob diese ignoriert, parallel oder in einer Queue verarbeitet werden, wird in dieser Phase bewusst offengelassen und nur als Planungs-Hinweis dokumentiert. Die konkrete Ausführungsstrategie wird später festgelegt.

---

## 13. API-Struktur (Minimal-API unter src/api.py)

- Eine Minimal-API wird in `src/api.py` bereitgestellt.
- Der Webserver lauscht auf dem in der Konfiguration definierten Port (Standard 8000).
- `start.py` startet den API-Server und bleibt aktiv, um Anfragen verarbeiten zu können.
- Die Minimal-API umfasst mindestens:
  - POST /start: löst den Start-Prozess aus (nicht-blockierend).
  - Optional GET /health: einfacher Health-Check.
- Die API darf den Event-Handling-Pfad nicht blockieren; Start-Prozesse werden asynchron oder in eigenen Threads/Tasks ausgeführt.

---

## 14. Globales Konfigurationssystem

Es gibt eine einzige globale Konfiguration. Die Struktur ist folgendermaßen vorgegeben:

```plaintext
+-- globale_configuration
|   |-- variablename
|   |   |-- beschreibung erklärung
|   |   |-- wert
|
+-- logging
|   |-- variablename
|   |   |-- beschreibung erklärung
|   |   |-- wert
|
+-- worker
    |-- variablename
    |   |-- beschreibung erklärung
    |   |-- wert
```

- Diese Konfiguration wird als Python-Struktur in `src/config.py` gepflegt und systemweit verwendet.
- Zugriff erfolgt zentral über `from src.config import CONFIG`.
- Der HTTP-Port wird ebenfalls in der globalen Konfiguration gepflegt (z. B. `CONFIG["globale_configuration"]["port"]["wert"]`).
- Logging-Parameter (Level, Aktivierung, Ausgabeziele) werden ausschließlich über `CONFIG` gesteuert.

---

## 15. Technische Anforderungen (Laufzeit und Architektur)

- Der Webserver darf beim Event-Handling nicht blockieren. HTTP-Handler delegieren die Start-Logik in asynchrone Tasks oder Threads.
- Start-Routinen laufen asynchron (z. B. asyncio/BackgroundTasks) oder in eigenen Threads, sodass die API schnell antwortet.
- Logging ist vollständig über die globale Konfiguration steuerbar (z. B. Level, Aktivierung).
- Modulstruktur:
  - start.py: Einstiegspunkt (startet Webserver, bleibt aktiv)
  - src/config.py: zentrale Konfiguration (`CONFIG`)
  - src/api.py: API-Definition (u. a. POST /start)
  - src/worker.py: Start-/Arbeitslogik (ausgelöst durch Events)
  - src/logger.py: Logging-Setup/-Zugriff

---

## 16. Beispiel-/Gerüstcode in Entworfener_Code

Hinweis: Es handelt sich um Struktur- und Ablaufgerüste (kein finaler Code, keine vollständige Implementierung). Ziel ist, Verantwortlichkeiten und Aufrufreihenfolge klar zu dokumentieren.

Beispiel src/config.py:
```python
# Globale Konfiguration als Python-Struktur (zentrale Quelle der Wahrheit)
CONFIG: dict = {
    "globale_configuration": {
        "port": {
            "beschreibung": "HTTP-Port des API-Servers",
            "wert": 8000,
        },
        "environment": {
            "beschreibung": "Laufzeitumgebung",
            "wert": "dev",
        },
    },
    "logging": {
        "enabled": {"beschreibung": "Aktiviert das Logging", "wert": True},
        "level": {"beschreibung": "Log-Level (z. B. INFO, DEBUG)", "wert": "INFO"},
    },
    "worker": {
        "concurrency": {
            "beschreibung": "Parallelisierungsgrad (Threads/Tasks), strategische Nutzung offen",
            "wert": 1,
        },
    },
}
```

Beispiel src/logger.py:
```python
import logging
from src.config import CONFIG

def get_logger(name: str) -> logging.Logger:
    logger = logging.getLogger(name)
    logger.setLevel(getattr(logging, str(CONFIG["logging"]["level"]["wert"]).upper(), logging.INFO))
    return logger
```

Beispiel src/worker.py:
```python
from typing import Any, Dict
from src.logger import get_logger

async def trigger_start(payload: Dict[str, Any]) -> None:
    logger = get_logger("worker")
    logger.info("Start-Event angenommen (Gerüst).")
```

Beispiel src/api.py:
```python
from typing import Any, Dict, Optional
from fastapi import FastAPI, BackgroundTasks
from pydantic import BaseModel
from src.config import CONFIG
from src.logger import get_logger
from src.worker import trigger_start

app = FastAPI(title="Minimal-API (Gerüst)")

class StartRequest(BaseModel):
    job_id: Optional[str] = None
    params: Optional[Dict[str, Any]] = None

@app.post("/start")
async def start_endpoint(req: StartRequest, background: BackgroundTasks) -> Dict[str, str]:
    logger = get_logger("api")
    logger.info("Start-Event empfangen (Gerüst).")
    background.add_task(trigger_start, (req.dict()))
    return {"status": "accepted"}
```

Ablauf-Skizze start.py (Beschreibung):
- Liest die globale Konfiguration aus `src/config.py` (oder eine projektspezifische Quelle).
- Initialisiert das Logging über `src/logger.py`.
- Startet den Webserver (z. B. `uvicorn src.api:app`) auf dem in `CONFIG` definierten Port und bleibt aktiv.
- Nicht-blockierender Betrieb: API antwortet unmittelbar; Arbeitslogik läuft asynchron/parallel.


## 17. Restart-/Reload-Funktion (über API)

Ziel
- Während der Laufzeit soll eine über die API verfügbare Funktion einen Neustart des Python-Prozesses anstoßen, um Konfigurationsänderungen zu übernehmen oder nach Laufzeiterweiterungen sauber durchzustarten.
- Endpunkte: `POST /restart` sowie Alias `POST /reload`.

Vorgaben
- Nicht-blockierend: Der HTTP-Handler bestätigt den Auftrag zeitnah und plant den Neustart im Hintergrund mit kurzer Verzögerung (z. B. 300–1000 ms), damit die Antwort noch übertragen werden kann.
- Prozess-Neustart: Entweder durch einen Vollneustart des Python-Prozesses (z. B. via os.execv) oder durch einen Supervisor (Docker/Compose/Systemd/K8s). In der Scaffold-Phase wird der direkte Prozess-Neustart skizziert.
- Konfiguration: Optionaler Request-Parameter `delay_ms` zur Steuerung der Verzögerung vor dem Neustart. Weitere Steuerung (z. B. Freigabe-Flag, Backoff) kann über die zentrale `CONFIG` erfolgen.
- Sicherheit/Robustheit (Hinweise):
  - Schutz vor Restart-Loops (Backoff/Minimum-Delay).
  - Optional Authentisierung/Autorisierung für administrative Endpunkte.
  - Log-Einträge vor Neustart (Grund, Zeitstempel, Kontext).
- Start-/Mehrfach-Events: Die Strategie für konkurrierende Ereignisse bleibt offen (ignorieren, parallel, Queue). Der Restart-Event ist administrativ und sollte priorisiert behandelt werden, Details werden in der späteren Implementierung festgelegt.

Schnittstellenbeschreibung (Minimal)
- `POST /restart` → Antwort: `{"status": "scheduled", "delay_ms": <int>}`
- `POST /reload` → Alias zu `/restart`

Modulzuordnung
- `src/api.py`: definiert die Endpunkte und plant den Neustart im Hintergrund.
- `src/worker.py`: enthält die Restart-Hilfsroutine (z. B. `restart_process(reason, delay_seconds)`), die nach einer kurzen Verzögerung den Prozess ersetzt/neustartet.
- `start.py`: bleibt dauerhaft aktiv; Neustart führt zur Neuinitialisierung inkl. erneuter Auswertung der Konfiguration.


## 3.2 Alternative Struktur: app/code-Aufteilung (empfohlen für klare Trennung)

Diese Variante verschiebt den ausführbaren Code, Tests und die API-Struktur unterhalb von `app/code`, während Konfigurationsdateien unter `app/config` leben. Einstiegspunkt und komponentenbezogene README liegen unter `app/`. Artefakte wie Dockerfile, docker-compose und requirements verbleiben auf oberster Ebene von `Entworfener_Code/`.

```plaintext
Entworfener_Code
├── app
│   ├── code
│   │   ├── api
│   │   │   ├── __init__.py
│   │   │   ├── router.py
│   │   │   └── routes
│   │   │       ├── execute.py
│   │   │       └── __init__.py
│   │   ├── app
│   │   │   └── main.py
│   │   ├── core
│   │   │   └── base_component.py
│   │   ├── src
│   │   │   ├── api.py
│   │   │   ├── config.py
│   │   │   ├── logger.py
│   │   │   └── worker.py
│   │   └── tests
│   │       └── test_smoke.py
│   ├── config
│   │   ├── config.yaml
│   │   └── logging.yaml
│   ├── README.md
│   └── start.py
├── docker-compose.yml
├── Dockerfile
└── requirements.txt
```

Leitlinien für diese Struktur:
- `app/start.py` bleibt dauerhaft aktiv (Webserver offen) und liest Konfiguration aus `app/config`.
- API für Start-Events und Admin-Endpunkte (POST `/start`, `/restart`, `/reload`) liegt in `app/code/src/api.py`. Diese Endpunkte dürfen nicht blockieren; Ausführung wird an `app/code/src/worker.py` delegiert (async/Threads).
- Zentrale, einzige globale Konfiguration als Python-Struktur in `app/code/src/config.py` (`from src.config import CONFIG`); YAML-Konfigurationsdateien ergänzen diese bei Bedarf (z. B. für externe Operatoren) und werden in `app/config` gepflegt.
- Logging wird über `CONFIG` gesteuert. Ein Gerüst für Logging-Zugriff liegt in `app/code/src/logger.py`; systemweite Handler/Formatter werden später konsolidiert.
- Die beispielhafte Router-Struktur für REST-Endpunkte liegt in `app/code/api` und wird in `app/code/app/main.py` eingebunden.
- Tests unter `app/code/tests` (pytest-Namenskonventionen `test_*.py`).

Hinweis zu Restart/Reload:
- Die Endpunkte `POST /restart` und `POST /reload` planen (nicht-blockierend) einen Prozessneustart ein, um Konfigurationsänderungen oder Erweiterungen aufzunehmen. Die konkrete Neustartstrategie (Supervisor/execv, Backoff, Auth) ist bewusst noch offen und wird in einer späteren Implementierungsphase festgelegt.