# Entwickler-Sektion: Überblick

<Lead>
Diese Sektion dokumentiert das **Platform-SDK**: die Bausteine, mit denen Tools für die Plattform entwickelt werden. Du findest hier die Referenz für jeden SDK-Namespace und den Leitfaden für den Aufbau eines kompletten Moduls.
</Lead>

<BetaNotice title="Vendor-Plattform in Planung">
Die externe Vendor-Plattform (dev.reosa.de) mit Einreichungs-Pipeline und Revenue-Share ist für Phase 4 geplant. Externe Tool-Einreichungen sind noch nicht geöffnet. Diese Seiten beschreiben den heutigen SDK-Stand, mit dem die Plattform-eigenen Tools gebaut werden: derselbe Vertrag gilt später auch für Vendor-Module.
</BetaNotice>

## Architektur in Kürze

- **Tool vs. Modul:** Ein *Tool* ist der Name, den Nutzer:innen im Marketplace sehen (z.B. "Zugangsdaten-Tresor"). Ein *Modul* ist die Code-Struktur dahinter: ein Ordner mit Manifest, Compute, UI und Tests. Ein Tool wird durch genau ein Modul implementiert.
- **Manifest als Single Source of Truth:** `manifest.ts` deklariert ID, Version, Kategorie, Credit-Kosten, Permissions, UI-Flächen, Lifecycle-Hooks und das Marketplace-Listing. CI validiert jedes Manifest gegen das Schema (`ModuleManifestSchema` aus `@reosa/sdk`).
- **Compute über den Runs-Harness:** Module exportieren eine `runTool`-Funktion. Der Plattform-Harness besitzt den kompletten Lauf-Lebenszyklus: Credits reservieren, Lauf ausführen, bei Erfolg committen, bei Fehler erstatten und benachrichtigen. Ein Modul fasst nie selbst Credits, Notifications oder Run-Tabellen an.
- **Reserve→Compute→Commit/Refund:** Jede credit-verbrauchende Aktion läuft über dieses Two-Phase-Pattern. Niemals direkt abbuchen. Details auf der [Credits-Seite](/dev/sdk/credits).
- **Context als erster Parameter:** Jeder server-seitige SDK-Aufruf nimmt einen `PlatformContext` (Tenant, User, Rolle, Permissions). Tenant-Isolation erzwingt Postgres-RLS, nicht dein Code.
- **Fehler-Hierarchie:** Alle SDK-Fehler erben von `SdkError` mit strukturiertem `code` und `details`. Du branchst mit `instanceof` (z.B. `InsufficientCreditsError`, `StorageQuotaExceededError`, `PermissionDeniedError`).

## Der Weg zu einem Tool

<CardGrid>
  <Card title="Modul-Guide" href="/dev/module-guide">
    Vom Scaffold zum lauffähigen Tool: Ordner-Struktur, Manifest, Compute-Vertrag, Lifecycle-Hooks, Validierung und Changelog-Regeln.
  </Card>
</CardGrid>

## SDK-Namespaces

<CardGrid>
  <Card title="Credits" href="/dev/sdk/credits">
    Reserve→Compute→Commit/Refund, Fehlerbilder, Anzeige-Regel für kleine Beträge und Add-on-Tools.
  </Card>
  <Card title="Storage" href="/dev/sdk/storage">
    Quota-geprüfte Writes, Bucket-Wahl per Key-Prefix und der saubere Umgang mit vollem Speicher.
  </Card>
  <Card title="Dateispeicher (Files)" href="/dev/sdk/files">
    Tool-Ausgaben sichtbar im Explorer ablegen, Dateien wählen lassen und teilen.
  </Card>
  <Card title="REOS AI" href="/dev/sdk/reos-ai">
    Tier-basierte KI ohne Modell-Namen, Abrechnungs-Modi und BYOK.
  </Card>
  <Card title="Notifications" href="/dev/sdk/notifications">
    In-App-Benachrichtigungen an einzelne Nutzer:innen oder Rollen, mit Action-Buttons.
  </Card>
  <Card title="Audit" href="/dev/sdk/audit">
    Der unveränderliche Audit-Trail: Namenskonvention, Metadaten-Regeln, Sichtbarkeit.
  </Card>
  <Card title="Compliance" href="/dev/sdk/compliance">
    AGG-Diskriminierungs-Check für Inserats-Texte und die AI-Risk-Klassen im Manifest.
  </Card>
  <Card title="Share" href="/dev/sdk/share">
    Zeitlich begrenzte, optional passwortgeschützte Links nach außen, mit Widerruf und Zähler.
  </Card>
  <Card title="Webhooks und Events" href="/dev/sdk/webhooks-und-events">
    Domain-Events emittieren, im Event-Katalog registrieren, Outbox-Zustellung verstehen.
  </Card>
</CardGrid>

## Grundregeln

1. **Externe Inputs immer mit Zod validieren**, bevor du sie verarbeitest. Das gilt auch für das `payload` deiner eigenen Tool-UI.
2. **Nie direkt auf Provider oder Storage zugreifen.** KI-Aufrufe laufen über [REOS AI](/dev/sdk/reos-ai), Datei-Writes über den [Dateispeicher](/dev/sdk/files) bzw. [Storage](/dev/sdk/storage). Direktzugriffe blockt der Reuse-Ratchet in CI.
3. **Frontend-Gating ist UX, Backend-Check ist Security.** Jede Permission wird an beiden Stellen geprüft (Defense in Depth).
4. **Keine PII in Logs und Telemetrie.** Nutzereingaben, Datei-Inhalte und Geheimnisse gehören nie nach Sentry oder PostHog.
5. **User-Trust gewinnt.** Jeder technische Fehler erstattet Credits automatisch; der Harness erledigt das, wenn dein Compute wirft.

Das Gegenstück für API-Integrationen (Webhooks empfangen, REST-API) findest du in der [API-Sektion](/api/overview).