Architecture Overview

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

System Architecture

Monorepo Structure

Apps

Packages

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/postbox/settings/*   # 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/settings/*           # 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.