Architecture Overview

Owlat follows a modern serverless architecture with real-time capabilities.

System Architecture

Monorepo Structure

Apps

Packages

Examples

Workspace members too (examples/conformance and examples/plugins/*), and not decoration: the reference plugins are one per trust tier and the conformance gallery drives them through the shipped host, codegen and CLI, so the plugin platform's extension points are proven by something that has to keep compiling.

Data Flow

Real-time Updates

Convex provides automatic real-time 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
    },
});

Authentication Flow

Email Sending Flow

Multi-tenancy

Within an Owlat instance, the Convex backend scopes all data to organizations via BetterAuth:

// 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();

Authentication Architecture

Email System Architecture

Database Schema Overview

The Convex schema (~97 tables, split into per-domain modules under apps/api/convex/schema/ and spread into defineSchema()) follows these patterns:

Core Tables

Contact Management

Email System

Automations

Settings & Security

Postbox (personal mail · flag: postbox)

See Postbox Architecture for the schema relationships, IMAP command flow, and inbound delivery routing.

Background Jobs

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

All scheduled jobs are registered in apps/api/convex/crons.ts — the authoritative list (34 jobs). A representative set:

Frontend Architecture

Layouts

• default - Public pages (landing, auth)
• dashboard - Authenticated pages with sidebar

Route Structure

/                               # 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)

Pages that belong to a toggleable area declare requiresFeature: '<flagKey>' in their definePageMeta block. The auth middleware redirects to a "feature off" placeholder when the flag is disabled, and Convex queries enforce the same check server-side.

State Management

• Convex queries provide reactive data
• useAuth() - Authentication state
• useOrganization() / useOrganizationContext() - Current organization context
• useMediaLibrary() - Media asset management
• useToast() - Global toast notifications
• useFocusMode() - Editor focus mode
• usePostHog() - Product analytics (capture events, identify users)
• usePostHogIdentity() - Auto-syncs auth/org state to PostHog

Feature Flags

Every toggleable product surface is declared once in packages/shared/src/featureFlags.ts — the single source of truth read by the setup CLI, the admin UI, the Convex backend, and Nuxt route middleware. See Feature flags — developer reference for the full registry and helper APIs.

The runtime pattern:

1. Registry — FEATURE_FLAGS declares each flag's category, default state, dependencies (requires, cascadesOff), required env vars, and Docker Compose profile.
2. Storage — current state lives in the Convex instanceSettings.featureFlags row.
3. Resolution — resolveFlags(stored) applies dependency rules and returns the effective state. Always use this before reading a flag.
4. Activation — turning a flag on activates its Docker Compose profile (recompiled into docker-compose.override.yml by owlat-setup) and validates its required env vars.
5. Enforcement — requiresFeature page meta gates routes; Convex queries call isFlagEnabled() server-side.

Providers

Where Owlat talks to an external system, it goes through a provider factory keyed off an env var. This lets self-hosters swap implementations without code changes. Today this is wired for LLM and email send; notifications and the vector store are declared env keys without an implemented factory yet.

There are no notification-provider or vector-store env keys: notifications are handled client-side by the desktop app, and knowledge retrieval uses Convex's built-in vector index (ctx.vectorSearch) directly. Analytics is PostHog, configured via POSTHOG_API_KEY / POSTHOG_HOST — there is no provider-factory abstraction and no ANALYTICS_PROVIDER switch.

See Providers for interface contracts and how to add a new provider.