Core Concepts

Architecture

Contd.ai follows a layered architecture designed for durability, scalability, and multi-tenancy.

System Overview

architecture.txt
┌─────────────────────────────────────────────────────────────┐
│                      Client SDKs                            │
│         (Python, TypeScript, Go, Java)                      │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                     API Gateway                             │
│         (Authentication, Rate Limiting, Routing)            │
└─────────────────────────────────────────────────────────────┘
                              │
              ┌───────────────┼───────────────┐
              ▼               ▼               ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│  Auth Service   │ │ Workflow Service│ │ Billing Service │
│                 │ │                 │ │                 │
│ - JWT Auth      │ │ - Orchestration │ │ - Usage Metering│
│ - API Keys      │ │ - State Machine │ │ - Subscriptions │
│ - RBAC          │ │ - Checkpointing │ │ - Invoicing     │
└─────────────────┘ └─────────────────┘ └─────────────────┘
              │               │               │
              └───────────────┼───────────────┘
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                     PostgreSQL                              │
│         (Workflow State, User Data, Billing)                │
└─────────────────────────────────────────────────────────────┘

Core Components

API Gateway

The API Gateway handles all incoming requests and provides:

  • •Authentication: JWT validation and API key verification
  • •Rate Limiting: Per-tenant request throttling
  • •Routing: Request routing to appropriate services
  • •Logging: Centralized request/response logging

Auth Service

Manages identity and access:

  • •User authentication (signup, login, password reset)
  • •Organization management
  • •API key generation and validation
  • •Role-based access control (RBAC)
  • •Audit logging

Workflow Service

The core execution engine:

  • •Workflow Registration: Store and version workflow definitions
  • •Execution: Run workflows with durable execution guarantees
  • •Checkpointing: Persist state after each step
  • •Recovery: Resume workflows from last checkpoint on failure
  • •Time-travel Debugging: Replay workflow execution history

Billing Service

Handles monetization:

  • •Usage metering and tracking
  • •Subscription management
  • •Invoice generation
  • •Payment processing integration

Durable Execution

Contd.ai guarantees durable execution through:

1. Event Sourcing

All workflow events are persisted to an append-only log

2. Checkpointing

State saved after each step completion

3. Idempotency

Steps can be safely retried without side effects

4. Deterministic Replay

Workflows can be replayed from history

Multi-Tenancy

Each organization operates in isolation:

  • •Separate database schemas per tenant
  • •Resource quotas and limits
  • •Independent API keys and permissions
  • •Isolated workflow execution contexts

Scalability

The architecture supports horizontal scaling:

  • •Stateless services behind load balancers
  • •Database connection pooling
  • •Async job processing for long-running tasks
  • •Event-driven communication between services