Convex Multi-Project Architecture

🚨 CRITICAL: This document is REQUIRED READING for anyone working with Convex in this project. All Convex-related work must follow this architecture.

Overview

The do.dev application uses a sophisticated multi-deployment Convex architecture to separate concerns, enable scalability, and provide isolation between different system components. This architecture separates authentication, local infrastructure, and application data into distinct Convex deployments for better organization and security.

🔍 Deployment Verification

Always verify deployments before making changes:

pnpm convex:verify

This runs a verification script that checks all Convex deployments are correctly configured and warns about any misconfigurations that could cause data loss.

Architecture Diagram

┌─────────────────────────────────────────────────────────────────┐
│                   do.dev Convex Architecture                   │
├─────────────────────────────────────────────────────────────────┤
│  Main Application Project (standing-bird-371)                  │
│  ├─ Core Business Logic                                         │
│  ├─ User Data Management                                        │
│  ├─ Customer Management                                         │
│  └─ Application State                                           │
├─────────────────────────────────────────────────────────────────┤
│  Local Infrastructure Project (agile-cardinal-285)             │
│  ├─ DNS Management                                              │
│  ├─ Traefik Proxy Configuration                                 │
│  ├─ Local Development Tools                                     │
│  └─ Infrastructure Monitoring                                   │
├─────────────────────────────────────────────────────────────────┤
│  Email Service Project (packages/convex-send)                  │
│  ├─ Email Templates                                             │
│  ├─ Email Analytics                                             │
│  ├─ Send Operations                                             │
│  └─ Delivery Management                                         │
└─────────────────────────────────────────────────────────────────┘

Project Breakdown

1. Main Application Project (`standing-bird-371`)

Purpose: Core do.dev application data and business logic

Location: tools/convex/

Deployment URL: https://standing-bird-371.convex.cloud

Key Responsibilities:

User Management: User profiles, authentication, and role-based access control
Customer Management: Customer data, billing, subscriptions
Application Logic: Core business functionality and workflows
Dashboard Data: Admin and user dashboard data
Organization Management: Multi-tenant organization and team structures

Schema Highlights:

users: {
  clerkId: string,
  email: string,
  name: string,
  role: "user" | "admin" | "super_admin" | "waitlist",
  organizations: Id<"organizations">[],
  lastActive: number
}

customers: {
  userId: Id<"users">,
  customerId: string,
  billingEmail: string,
  subscription: {
    plan: "free" | "pro" | "enterprise",
    status: "active" | "cancelled" | "past_due"
  }
}

organizations: {
  name: string,
  slug: string,
  ownerId: Id<"users">,
  members: {
    userId: Id<"users">,
    role: "owner" | "admin" | "member",
    joinedAt: number
  }[]
}

Environment Variables:

# Main application deployment
CONVEX_URL=https://standing-bird-371.convex.cloud
NEXT_PUBLIC_CONVEX_URL=https://standing-bird-371.convex.cloud

2. Local Infrastructure Project (`agile-cardinal-285`)

Purpose: Local development infrastructure and proxy management

Location: packages/convex-local/

Deployment URL: https://agile-cardinal-285.convex.cloud

Key Responsibilities:

DNS Management: Local DNS server configuration and record management
Traefik Proxy: Dynamic reverse proxy configuration and health monitoring
Infrastructure Monitoring: Service health checks and status reporting
Development Tools: Local development environment support

Schema Highlights:

proxy_routes: {
  domain: string,
  upstreamId: Id<"proxy_upstreams">,
  priority: number,
  isActive: boolean
}

proxy_upstreams: {
  name: string,
  addresses: [                  // Multiple upstream addresses
    { host: string, port: number, priority: number }
  ]
}

dns_records: {
  zone: string,
  name: string,
  type: "A" | "CNAME" | "MX",
  value: string
}

Environment Variables:

# In dodev app
CONVEX_DEPLOYMENT_LOCAL=dev:agile-cardinal-285
NEXT_PUBLIC_CONVEX_DEPLOYMENT_LOCAL=https://agile-cardinal-285.convex.cloud

3. Email Service Project

Purpose: Dedicated email service for sending and tracking emails

Location: packages/convex-send/

Key Responsibilities:

Email Templates: Manage and store email templates
Email Sending: Handle email delivery operations
Email Analytics: Track open rates, click rates, and delivery status
Email Management: Organize email campaigns and sequences

Schema Highlights:

emailTemplates: {
  name: string,
  subject: string,
  htmlContent: string,
  textContent: string,
  variables: string[],
  isActive: boolean
}

emailSends: {
  templateId: Id<"emailTemplates">,
  recipientEmail: string,
  variables: Record<string, string>,
  status: "queued" | "sent" | "delivered" | "failed",
  sentAt?: number,
  deliveredAt?: number,
  openedAt?: number
}

emailAnalytics: {
  sendId: Id<"emailSends">,
  event: "sent" | "delivered" | "opened" | "clicked" | "bounced",
  timestamp: number,
  metadata?: Record<string, any>
}

# Main application data (business logic, users, customers)
CONVEX_URL=https://standing-bird-371.convex.cloud
NEXT_PUBLIC_CONVEX_URL=https://standing-bird-371.convex.cloud

# Local Infrastructure (DNS, Traefik, Dev Tools)
CONVEX_DEPLOYMENT_LOCAL=dev:agile-cardinal-285
NEXT_PUBLIC_CONVEX_DEPLOYMENT_LOCAL=https://agile-cardinal-285.convex.cloud

# Email Service
CONVEX_DEPLOYMENT_SEND=[email-service-deployment]
NEXT_PUBLIC_CONVEX_DEPLOYMENT_SEND=[email-service-url]

Configuration Patterns

Multi-Client Setup (dodev app)

// Main application client
const convex = new ConvexReactClient(process.env.NEXT_PUBLIC_CONVEX_URL!);

// Local infrastructure client
const localConvex = new ConvexHttpClient(
  process.env.NEXT_PUBLIC_CONVEX_DEPLOYMENT_LOCAL!
);

// Email service client
const emailConvex = new ConvexHttpClient(
  process.env.NEXT_PUBLIC_CONVEX_DEPLOYMENT_SEND!
);

// Usage examples:
const users = await convex.query("users.list");
const domains = await localConvex.query("proxy.listRoutes");
const emailStats = await emailConvex.query("analytics.getStats");

Development Workflow

1. Working with Convex Deployments

# Navigate to main convex directory
cd tools/convex

# Start development
npx convex dev

# Deploy to production
npx convex deploy

# Generate TypeScript types
npx convex codegen

2. Local Infrastructure Management

The dodev app manages local infrastructure through the dedicated deployment:

// DNS management
const zones = await localConvex.query("dns.listZones");

// Proxy configuration
const routes = await localConvex.query("proxy.listRoutes");

// Health monitoring
const status = await localConvex.query("health.getSystemStatus");

3. Email Service Integration

Email operations use the dedicated email service deployment:

// Send email
const emailResult = await emailConvex.mutation("emails.send", {
  templateId: "welcome",
  recipientEmail: user.email,
  variables: { name: user.name }
});

// Track email analytics
const stats = await emailConvex.query("analytics.getEmailStats");

Cross-Deployment Communication

Application Data Flow

1. User authentication and management → Main application deployment
2. Local infrastructure operations → Local infrastructure deployment
3. Email operations → Email service deployment
4. All deployments coordinate through the dodev application

Infrastructure Management Flow

1. dodev app manages local infrastructure
2. DNS changes → localConvex.mutation("dns.updateRecord")
3. Proxy config → localConvex.mutation("proxy.updateRoute")
4. Infrastructure monitoring through dedicated deployment

Email Service Flow

1. dodev app triggers email operations
2. Email templates → emailConvex.query("templates.get")
3. Send operations → emailConvex.mutation("emails.send")
4. Analytics tracking → emailConvex.query("analytics.getStats")

✅ Allowed Cross-Deployment Access

dodev app → Local infrastructure (admin functions)
dodev app → Email service (email operations)
All deployments ← dodev app (coordinated access)

❌ Prohibited Cross-Deployment Access

Direct cross-deployment queries (use proper client setup)
Unauthorized deployment access (security isolation)
Direct database access (use proper Convex functions)

Security & Permissions

Deployment Isolation

Each deployment has separate schemas and cannot access others' data directly
Authentication is managed through the main application deployment
Local infrastructure access is restricted to the dodev application only

User Role Management

// In main application schema
users: {
  clerkId: string,
  role: "user" | "admin" | "super_admin" | "waitlist",
  organizations: Id<"organizations">[],
  permissions: {
    canManageInfrastructure: boolean,
    canSendEmails: boolean,
    canManageUsers: boolean
  }
}

Environment Security

Never hardcode deployment URLs in source code
Use environment variables for all Convex endpoints
Separate development and production deployments
Rotate secrets regularly and update environment configs

Deployment Guide

Production Deployment Checklist

Environment Variables:
- NEXT_PUBLIC_CONVEX_URL configured (main application)
- NEXT_PUBLIC_CONVEX_DEPLOYMENT_LOCAL configured (infrastructure)
- NEXT_PUBLIC_CONVEX_DEPLOYMENT_SEND configured (email service)
Authentication Setup:
- Clerk authentication configured
- User roles and permissions implemented
- Organization management configured
Cross-Deployment Testing:
- User authentication flow tested
- Infrastructure access tested
- Email service integration tested
Monitoring Setup:
- Health checks configured
- Error logging implemented
- Performance monitoring enabled

// Problem: Infrastructure or email service connection failing
// Solution: Check deployment URLs in environment variables
const localConvex = new ConvexHttpClient(
  process.env.NEXT_PUBLIC_CONVEX_DEPLOYMENT_LOCAL! // Must be correct
);

2. Missing Environment Variables

# Check all required variables are set
echo $NEXT_PUBLIC_CONVEX_URL
echo $NEXT_PUBLIC_CONVEX_DEPLOYMENT_LOCAL
echo $NEXT_PUBLIC_CONVEX_DEPLOYMENT_SEND

3. Permission Issues

// Ensure user has proper permissions for infrastructure or email access
// Check user role and permissions in main application deployment

Debug Commands

# Check main application
cd tools/convex
npx convex run users:list

# Check local infrastructure
cd packages/convex-local  
npx convex run proxy:listRoutes

# Check email service
cd packages/convex-send
npx convex run analytics:getStats

Migration Guide

Expanding the Multi-Deployment Architecture

Identify Service Boundaries:
- Core application data → Main deployment
- Infrastructure data → Local infrastructure deployment
- Email operations → Email service deployment

Create New Service Deployments:

# In new service directory
npx convex dev

Update Environment Variables:
- Add service-specific deployment URLs
- Update client configurations
- Test cross-deployment communication
Migrate Functions:
- Separate concerns into appropriate deployments
- Update client calls to use appropriate services
- Maintain data consistency across deployments
Test Integration:
- Cross-deployment functionality
- Service isolation
- Performance impact

Best Practices

1. Deployment Responsibility Separation

Main application: Core business logic, user management, and customer data
Infrastructure deployment: Only local development tools and DNS/proxy management
Email service: Only email-related operations and analytics
Never mix concerns across deployment boundaries

2. Environment Management

Use consistent naming for environment variables
Document all required variables for the application
Test with missing variables to ensure graceful degradation

3. Error Handling

// Always handle cross-deployment failures gracefully
try {
  const result = await localConvex.query("proxy.listRoutes");
} catch (error) {
  console.error("Infrastructure service failed:", error);
  // Implement fallback behavior
}

4. Performance Optimization

Cache cross-deployment calls when appropriate
Batch operations to reduce network calls
Use appropriate timeouts for cross-deployment communication

5. Development Workflow

Test cross-deployment communication early
Document service-specific configuration requirements
Use consistent patterns across all deployments

Future Considerations

Planned Improvements

Production Environment: Separate production deployments for each service
Automated Deployment: CI/CD pipelines for each Convex deployment
Enhanced Monitoring: Cross-deployment observability and alerting
Schema Validation: Automated validation of cross-deployment interfaces

Scaling Patterns

Regional Deployments: Geo-distributed Convex deployments
Load Balancing: Multiple instances of high-traffic services
Data Partitioning: Horizontal scaling strategies
Caching Layer: Redis integration for frequently accessed data

Summary

This multi-deployment Convex architecture provides:

Clear separation of concerns between application data, infrastructure, and email services
Scalable foundation for the do.dev application
Security isolation between different system components
Centralized application management through the main deployment
Dedicated infrastructure management for local development
Specialized email service for communication needs

Remember: This architecture is designed for long-term scalability and maintainability. Follow the patterns established here for all new Convex development.

On this page