Convex-Datenbank

Wie CodeCourier Convex als reaktive Echtzeit-Datenbank für den gesamten Anwendungszustand nutzt – inklusive Schemadesign, Queries, Mutations und Echtzeit-Abonnements.

8 min Lesezeit
convexdatabasereactive

Convex ist die reaktive Backend-Plattform, die als zentraler Datenspeicher und Koordinationsschicht für CodeCourier dient. Jeder Bestandteil des Anwendungszustands -- Benutzer, Projekte, Sandboxes, Workflows, Runs, Nachrichten, Learnings, Nutzungsdaten und mehr -- liegt in Convex. Was Convex gegenüber klassischen Datenbanken einzigartig macht, ist die eingebaute Reaktivität: Sobald sich Daten ändern, wird jeder abonnierte Client automatisch benachrichtigt und stellt den neuesten Zustand dar. Diese Seite erläutert, wie CodeCourier Convex einsetzt, das Schemadesign sowie Codemuster für die Arbeit mit der Datenbank.

Was Convex bietet

  • Echtzeit-Abonnements -- Queries werden automatisch erneut ausgeführt, wenn sich die zugrunde liegenden Daten ändern. Das Dashboard zeigt Sandbox-Status, Run-Fortschritt und Nachrichten in Echtzeit ohne Polling an.
  • Transaktionale Mutations -- Jede Mutation läuft in einer serialisierbaren Transaktion. Lese- und Schreibvorgänge innerhalb einer Mutation sind atomar, was Race Conditions verhindert.
  • Typsichere Funktionen -- Queries, Mutations und Actions werden in TypeScript mit vollständiger Typinferenz definiert. Das Convex-Schema validiert Argumente und Rückgabe- typen zur Laufzeit.
  • Actions für Seiteneffekte -- Operationen, die externe Dienste aufrufen (E2B, Trigger.dev), werden als Actions definiert. Diese können Daten lesen und Mutations einplanen, sind selbst aber nicht transaktional.
  • Eingebaute Authentifizierung -- Convex validiert Clerk-JWTs und stellt die authentifizierte Benutzeridentität in jeder Funktion bereit.
  • Geplante Funktionen -- Die API ctx.scheduler.runAfter ermöglicht eine verzögerte Ausführung, etwa für asynchrone Operationen wie das Dispatchen der Learning-Extraktion.
  • Dateispeicherung -- Convex bietet eingebaute Dateispeicherung (die Tabelle _storage), die für Referenzbilder und Projektlogos verwendet wird.

Schema-Übersicht

Das Convex-Schema ist in convex/schema.ts definiert und umfasst über zwanzig Tabellen. Hier die wichtigsten Entitäts- gruppen:

Identität und Zugriff

  • users -- Aus Clerk synchronisierte Benutzerkonten. Indiziert nach clerkId und email.
  • projects -- Übergeordnete Organisationseinheiten. Indiziert nach ownerId und slug.
  • projectMembers -- Many-to-many-Beziehung zwischen Benutzern und Projekten mit Rollen (owner, admin, member) und Einladungsstatus.
  • projectSettings -- Projektspezifische Konfiguration einschließlich System-Prompts, CLAUDE.md, Umgebungsvariablen, ausgewählter Skills und Commands sowie Deploy Keys.
  • userSettings -- Benutzerspezifische Einstellungen wie zuletzt aktives Projekt.

API-Keys

  • apiKeys -- API-Keys für Provider auf Benutzerebene (E2B, Anthropic, OpenRouter, OpenAI, GitHub). Verschlüsselt gespeichert mit Anzeige der letzten vier Zeichen.
  • projectProviderKeys -- Provider-API-Keys auf Projektebene, die Keys auf Benutzerebene überschreiben.
  • projectApiKeys -- CodeCourier-REST-API-Keys für den programmatischen Zugriff. SHA-256-gehasht, widerrufbar und mit Nutzungs-Tracking.

Ausführung

  • sandboxes -- E2B-Sandbox-Instanzen mit Status, Konfiguration und Lebenszyklus-Tracking.
  • sandboxMessages -- Konversationsnachrichten zwischen Benutzern und KI-Agents innerhalb von Sandboxes.
  • workflows -- Workflow-Blueprints, die Pipeline-Typ, Schritte und Standardkonfiguration definieren.
  • runs -- Workflow-Ausführungsinstanzen mit Status, Fortschritt und PR-Tracking.
  • runSteps -- Einzelne Ausführungsschritte innerhalb von Runs (Designer, Checker, Optimizer usw.).
  • workChains -- Sequenzielle Issue-Ausführungsketten.

KI-Wissen

  • personas -- KI-Agent-Persönlichkeiten mit benutzerdefinierten Anweisungen, Skills und Modellpräferenzen.
  • skills / skillFiles -- Skill- Definitionen und ihre Dateiinhalte.
  • commands -- Wiederverwendbare Command-Definitionen.
  • scripts -- Skriptdefinitionen für die Sandbox- Ausführung.
  • learnings -- Aus Sandbox-Sessions extrahiertes Wissen.
  • learningVersions -- Kompilierte Learning-Snapshots zur Einspeisung in zukünftige Sessions.

Issues

  • issueSessions -- Datensätze zu Issue-Discovery- Sessions.
  • issues -- Einzelne Issues, die während Sessions entdeckt oder manuell erstellt wurden.

Analytik und Nutzung

  • usageCostRates -- Kostentarife für verschiedene Dienste (Claude Code, E2B, Trigger.dev, Convex usw.) mit konfigurierbaren Tariftypen und Modellklassen.
  • usageRecords -- Detaillierte Nutzungsdaten pro Projekt, Dienst und Datum, mit optionalen Enterprise-Tracking- Feldern für Token-Anzahlen, Modell-IDs und Step-Zuordnung.
  • projectCounters -- Denormalisierte Zähler für den schnellen Zugriff auf Anzahlen von Sandboxes, Runs, Workflows und Mitgliedern.
  • dailyStats -- Tägliche aggregierte Statistiken zur Projektaktivität.
  • notifications -- Benachrichtigungsdatensätze für Run-Abschlüsse, PR-Ereignisse und Team-Aktivitäten.

Echtzeit-Queries

Das Dashboard von CodeCourier nutzt die Echtzeit-Query-Abonnements von Convex umfassend. Wenn Sie eine Sandbox-Konversation anzeigen, abonniert die Query sandboxMessages.listBySandbox alle Nachrichten dieser Sandbox. Sobald eine neue Nachricht vom KI-Agent eintrifft (geschrieben von einem Trigger.dev-Task über den Callback-Endpoint), wird die Query automatisch erneut ausgeführt und die UI aktualisiert sich sofort -- ohne Polling, ohne WebSocket-Setup, ohne manuelle Invalidierung.

Wichtige Queries, die im Dashboard verwendet werden:

  • sandboxes.listPaginated -- Versorgt die Sandbox- Listenansicht mit cursorbasierter Paginierung.
  • runs.listPaginated -- Versorgt die Runs-Listen- ansicht.
  • workflows.listForProject -- Lädt alle Workflows für das aktuelle Projekt.
  • sandboxMessages.listBySandbox -- Streamt die Konversation in Echtzeit.
  • runSteps.listByRun -- Zeigt den schrittweisen Fortschritt während der Workflow-Ausführung.
  • usage.getProjectUsageSummary -- Echtzeit- Nutzungsdaten für das Dashboard.

Mutations

Mutations in Convex sind transaktionale Schreibvorgänge. CodeCourier verwendet Mutations für alle vom Benutzer initiierten Zustands- änderungen:

  • Erstellen, Aktualisieren und Löschen von Workflows
  • Umbenennen von Sandboxes und Runs
  • Verwaltung von Projektmitgliedern und Einladungen
  • Erstellen und Widerrufen von API-Keys
  • Aktualisieren von Projekteinstellungen
  • Erfassen der Nutzung und Upsert von Kostentarifen

Interne Mutations (mit dem Präfix internal) werden von Trigger.dev-Callbacks und geplanten Funktionen verwendet. Sie sind vom Frontend aus nicht erreichbar.

Indizes

Das Schema definiert umfangreiche Indizes für effiziente Abfragen. Jede Tabelle besitzt mindestens einen Index zusätzlich zum Standard-Index _id. Wichtige Index-Muster sind:

  • by_user / by_project -- Filtert Datensätze nach Eigentümerschaft.
  • by_deleted -- Filtert weich gelöschte Datensätze effizient heraus.
  • by_status -- Filtert nach Lebenszyklus-Zustand.
  • by_project_date -- Zeitreihen-Abfragen für Analytik.
  • by_key -- API-Key-Suche per Hash.

Arbeiten mit Convex in CodeCourier

Frontend-Queries

Das Dashboard nutzt den Hook useQuery aus dem Convex-React-Client:

const sandboxes = useQuery(api.sandboxes.listPaginated, {
  paginationOpts: { numItems: 20 }
});

Queries geben während des Ladens undefined zurück und aktualisieren sich automatisch, wenn sich die zugrunde liegenden Daten ändern.

Frontend-Mutations

Mutations werden über den Hook useMutation aufgerufen:

const rename = useMutation(api.sandboxes.renameSandbox);
await rename({ id: sandboxId, name: "New Name" });

Frontend-Actions

Actions, die externe Operationen auslösen, verwenden useAction:

const launch = useAction(api.sandboxActions.launchSandboxes);
await launch({ config, prompt, projectId });