Architekturüberblick

Owlat folgt einer modernen Serverless-Architektur mit Echtzeitfähigkeiten.

Systemarchitektur

Monorepo-Struktur

Apps

Packages

Beispiele

Ebenfalls Workspace-Mitglieder (examples/conformance und examples/plugins/*) und keine Dekoration: Die Referenz-Plugins gibt es eines pro Trust-Stufe, und die Conformance-Galerie treibt sie durch den ausgelieferten Host, Codegen und die CLI — so werden die Erweiterungspunkte der Plugin-Plattform durch etwas belegt, das weiterhin kompilieren muss.

Datenfluss

Echtzeit-Updates

Convex liefert automatische Echtzeit-Updates:

// Frontend - automatically re-renders when data changes
const contacts = useConvexQuery(api.contacts.contacts.list, {});

// Backend - changes automatically push to subscribed clients
export const create = mutation({
    handler: async (ctx, args) => {
        await ctx.db.insert('contacts', { ...args });
        // Clients subscribed to list queries automatically update
    },
});

Authentifizierungsablauf

Ablauf des E-Mail-Versands

Mandantenfähigkeit

Innerhalb einer Owlat-Instanz grenzt das Convex-Backend alle Daten über BetterAuth auf Organisationen ein:

// Schema pattern - every table has organizationId
contacts: defineTable({
    organizationId: v.string(),
    // ... other fields
}).index('by_org', ['organizationId']);

// Query pattern - always filter by organization
const contacts = await ctx.db
    .query('contacts')
    .withIndex('by_org', (q) => q.eq('organizationId', organizationId))
    .collect();

Authentifizierungsarchitektur

Architektur des E-Mail-Systems

Überblick über das Datenbankschema

Das Convex-Schema (~97 Tabellen, aufgeteilt in Module pro Domäne unter apps/api/convex/schema/ und in defineSchema() hineingespreizt) folgt diesen Mustern:

Kerntabellen

Kontaktverwaltung

E-Mail-System

Automatisierungen

Einstellungen & Sicherheit

Postbox (persönliche Mail · Flag: postbox)

Die Schemabeziehungen, den IMAP-Kommandofluss und das Routing der eingehenden Zustellung finden Sie unter Postbox-Architektur.

Hintergrundjobs

Backend (apps/api/convex/crons.ts)

Alle geplanten Jobs sind in apps/api/convex/crons.ts registriert — die maßgebliche Liste (34 Jobs). Eine repräsentative Auswahl:

Frontend-Architektur

Layouts

• default - Öffentliche Seiten (Landingpage, Auth)
• dashboard - Authentifizierte Seiten mit Seitenleiste

Routen-Struktur

/                               # Landing page
/auth/login                     # Login
/auth/register                  # Registration
/auth/forgot-password           # Password reset request
/auth/reset-password            # Password reset form
/dashboard                      # Main dashboard
/dashboard/send/*               # Email templates, blocks, media library
/dashboard/send/media           # Media library
/dashboard/send/emails/*             # Email editor
/dashboard/campaigns/*          # Campaign management            (flag: campaigns)
/dashboard/automations/*        # Automation workflows            (flag: automations)
/dashboard/send/transactional/*      # Transactional templates         (flag: transactional)
/dashboard/audience/*           # Contacts, topics, segments
/dashboard/inbox/*              # Shared team inbox + triage      (flag: inbox)
/dashboard/chat/*               # Real-time chat                  (flag: chat)
/dashboard/postbox/*            # Personal mailbox webmail UI     (flag: postbox)
/dashboard/preferences/*   # Aliases, filters, app passwords (flag: postbox)
/dashboard/knowledge/*          # Knowledge graph                 (flag: ai.knowledge)
/dashboard/visualizations       # AI dashboards                   (flag: ai.visualizations)
/dashboard/files/*              # File browser
/archive/:token                 # Campaign archive (public)
/dashboard/admin/*           # Organization settings (incl. Features)

Seiten, die zu einem umschaltbaren Bereich gehören, deklarieren requiresFeature: '<flagKey>' in ihrem definePageMeta-Block. Die Auth-Middleware leitet auf einen Platzhalter „Feature deaktiviert“ um, wenn das Flag ausgeschaltet ist, und Convex-Queries erzwingen dieselbe Prüfung serverseitig.

State Management

• Convex-Queries liefern reaktive Daten
• useAuth() - Authentifizierungszustand
• useOrganization() / useOrganizationContext() - Aktueller Organisationskontext
• useMediaLibrary() - Verwaltung von Medien-Assets
• useToast() - Globale Toast-Benachrichtigungen
• useFocusMode() - Fokusmodus des Editors
• usePostHog() - Produktanalytik (Events erfassen, Benutzer identifizieren)
• usePostHogIdentity() - Synchronisiert Auth-/Org-Zustand automatisch zu PostHog

Feature-Flags

Jede umschaltbare Produktoberfläche wird genau einmal in packages/shared/src/featureFlags.ts deklariert — die Single Source of Truth, die das Setup-CLI, die Admin-Oberfläche, das Convex-Backend und die Nuxt-Route-Middleware lesen. Die vollständige Registry und die Helfer-APIs finden Sie unter Feature-Flags — Entwicklerreferenz.

Das Laufzeitmuster:

1. Registry — FEATURE_FLAGS deklariert für jedes Flag Kategorie, Standardzustand, Abhängigkeiten (requires, cascadesOff), benötigte Umgebungsvariablen und das Docker-Compose-Profil.
2. Speicherung — der aktuelle Zustand liegt in der Convex-Zeile instanceSettings.featureFlags.
3. Auflösung — resolveFlags(stored) wendet die Abhängigkeitsregeln an und liefert den effektiven Zustand. Nutzen Sie das immer, bevor Sie ein Flag lesen.
4. Aktivierung — ein Flag einzuschalten aktiviert sein Docker-Compose-Profil (von owlat-setup in die docker-compose.override.yml neu kompiliert) und validiert die dafür nötigen Umgebungsvariablen.
5. Durchsetzung — die Page-Meta requiresFeature sperrt Routen; Convex-Queries rufen serverseitig isFlagEnabled() auf.

Provider

Wo Owlat mit einem externen System spricht, geschieht das über eine Provider-Factory, die an einer Umgebungsvariable hängt. Damit können Self-Hoster Implementierungen ohne Codeänderungen austauschen. Heute ist das für LLM und E-Mail-Versand verdrahtet; Benachrichtigungen und der Vector Store sind deklarierte Env-Schlüssel ohne bislang implementierte Factory.

Es gibt keine Env-Schlüssel für Notification-Provider oder Vector Store: Benachrichtigungen werden clientseitig von der Desktop-App erledigt, und der Knowledge-Abruf nutzt direkt den eingebauten Vektorindex von Convex (ctx.vectorSearch). Für Analytics kommt PostHog zum Einsatz, konfiguriert über POSTHOG_API_KEY / POSTHOG_HOST — es gibt weder eine Provider-Factory-Abstraktion noch einen ANALYTICS_PROVIDER-Schalter.

Interface-Contracts und die Vorgehensweise beim Hinzufügen eines neuen Providers finden Sie unter Provider.