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.listFromSession, {});

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

Owlat has two levels of multi-tenancy:

1. Platform-level — The control plane (apps/nest-api) manages multiple VPS instances, one per customer organization. Each VPS runs an isolated Docker Compose stack.
2. Tenant-level — Within each VPS, the Convex backend scopes all data to organizations via BetterAuth (the pattern below).

All data is scoped 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

Control Plane Architecture

The control plane (apps/nest-api/) manages the lifecycle of customer organizations. Each organization gets a dedicated VPS on Hetzner Cloud running a full Docker Compose stack.

Provisioning Flow

Per-VPS Stack

Each provisioned VPS runs six Docker services:

Edge Routing

A Caddy reverse proxy reads the routingTable in the control plane database to map organization slugs to VPS IP addresses. When an organization is suspended or deleted, its routing entry is deactivated.

Available Regions

VPS instances can be provisioned in six Hetzner Cloud datacenters:

VPS Health Monitoring

The control plane runs health checks every 5 minutes against all running VPS instances, probing three services:

Status Levels

Auto-Recovery

• Alert at 3 consecutive failures (15 minutes) — creates a health alert for admins
• Auto-reboot at 6 consecutive failures (30 minutes) — triggers Hetzner server reboot via API

Database Schema Overview

The Convex schema (~30 tables) follows these patterns:

Core Tables

Contact Management

Email System

Automations

Settings & Security

Control Plane Tables (apps/nest-api)

Background Jobs

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

Control Plane (apps/nest-api/convex/crons.ts)

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/mail/*               # Email templates, blocks, media library
/dashboard/mail/media           # Media library
/dashboard/emails/*             # Email editor
/dashboard/campaigns/*          # Campaign management
/dashboard/audience/*           # Contacts, lists, segments
/dashboard/automations/*        # Automation workflows
/dashboard/transactional/*      # Transactional templates
/archive/:token                 # Campaign archive (public)
/dashboard/settings/*           # Organization settings

State Management

• Convex queries provide reactive data
• useAuth() - Authentication state
• useCurrentOrganization() - 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

Some features are toggled via environment variables and can be enabled or disabled at runtime without code changes.

Backend helpers live in apps/api/convex/lib/. Frontend composables read from useRuntimeConfig().public and conditionally subscribe to Convex queries. The pattern:

1. Backend: a small lib/*.ts file reads process.env and exports boolean helpers.
2. Frontend: a useFeature() composable exposes reactive flags and conditional query subscriptions.
3. Middleware: auth.ts and guest.ts check the composable and redirect as needed.
4. UI: sidebar nav items and settings cards are conditionally rendered.