CodeAI - Declarative Backend Framework for LLMs

Why CodeAI?

A declarative backend framework designed from the ground up for LLM code generation. Write less, deploy more.

LLM-Friendly Syntax

Declarative constructs optimized for AI token prediction patterns. LLMs write .cai specs that compile to production-ready Go code.

Production Ready

Built-in authentication (JWT, JWKS), Redis caching, Temporal workflows, and Asynq job queues. Everything you need for enterprise backends, out of the box.

Type Safe

Go-powered runtime with compile-time type checking. Catch errors before deployment with strict validation and AST analysis during the build phase.

Fault Tolerant

Flexible whitespace handling and lenient syntax variations. Graceful error recovery ensures your specs parse even with minor formatting issues.

OpenAPI Generation

Automatic OpenAPI 3.0 specification generation from your DSL. Get interactive API documentation and client SDKs without any extra configuration.

Enterprise Features

Temporal SDK for durable workflows, Asynq for distributed job scheduling, Redis caching with circuit breakers, and Prometheus metrics built-in.

Zero Boilerplate

No manual routing, middleware setup, or SQL queries. Define your entities and APIs declaratively; the runtime handles the rest automatically.

Open Source

MIT licensed and community-driven. Contribute, customize, and deploy without vendor lock-in. Full transparency and freedom to extend.

How It Works

From declarative specs to production APIs in seconds. Watch your .cai files transform into a fully-featured backend.

DSL Layer

.cai Files

Parser

Participle v2

Go Runtime

Production Engine

REST API

OpenAPI 3.0

DSL Layer

.cai declarative specifications

Parser

Participle v2 lexer & AST

Go Runtime

Chi, PostgreSQL, MongoDB, Redis, Temporal, Asynq

REST API

OpenAPI 3.0 with auto-generated docs

Go 1.24+

PostgreSQL

MongoDB

Redis

Temporal

Asynq

Prometheus

Quick Start

Get Started in Minutes

From zero to a running API in four simple steps. No complex configuration required.

1

Install CodeAI

Install the CodeAI CLI with a single command. Requires Go 1.24+ installed on your system.

terminal

# Install CodeAI CLI
curl -sSL https://raw.githubusercontent.com/bargom/codeai/main/install.sh | sh

2

Create Your First .cai File

Define your MongoDB collection and REST API endpoints in a single declarative file. This example shows full CRUD operations with validation, type-safe handlers, and automatic route registration.

app.cai

# Create app.cai
cat > app.cai << 'EOF'
config {
  database_type: "mongodb"
  mongodb_uri: "mongodb://localhost:27017"
  mongodb_database: "myapp"
}

database mongodb {
  collection User {
    _id: objectid, primary, auto
    name: string, required
    email: string, required, unique
    age: int, optional
    created_at: date, auto
  }
}

// REST API Endpoints
endpoint POST "/users" {
  request CreateUserRequest from body
  response User status 201

  do {
    validate(request)
    insert("users", request)
  }
}

endpoint GET "/users/:id" {
  request User from path
  response User status 200

  do {
    validate(id)
    query("users", id)
  }
}

endpoint PUT "/users/:id" {
  request UpdateUserRequest from body
  response User status 200

  do {
    validate(id)
    validate(request)
    update("users", id, request)
  }
}

endpoint DELETE "/users/:id" {
  response Empty status 204

  do {
    validate(id)
    delete("users", id)
  }
}
EOF

3

Start the Server

Start MongoDB with Docker, then launch CodeAI. It parses your .cai file and automatically registers all your REST endpoints.

terminal

# Start MongoDB
docker run -d --name mongodb -p 27017:27017 mongo:7

# Start CodeAI (reads config from app.cai)
codeai server start

# Output:
INFO  Connected to MongoDB
INFO  Registered endpoint: POST /users
INFO  Registered endpoint: GET /users/:id
INFO  Registered endpoint: PUT /users/:id
INFO  Registered endpoint: DELETE /users/:id
INFO  Server listening on localhost:8080

4

Test Your REST API

Test your endpoints with curl. All CRUD operations are automatically available based on your endpoint definitions.

terminal

# Create a user
curl -X POST http://localhost:8080/users \
  -H "Content-Type: application/json" \
  -d '{"name":"Alice","email":"alice@example.com","age":25}'

# Get user by ID
curl http://localhost:8080/users/507f1f77bcf86cd799439011

# Update user
curl -X PUT http://localhost:8080/users/507f1f77bcf86cd799439011 \
  -H "Content-Type: application/json" \
  -d '{"name":"Alice Smith","age":26}'

# Delete user
curl -X DELETE http://localhost:8080/users/507f1f77bcf86cd799439011

View Examples

See It In Action

Explore real .cai examples. Click on the tabs below to see different features.

simple-api.cai

// Define REST endpoints with minimal syntax
endpoint GET /tasks {
    description: "List all tasks with filtering"
    auth: optional

    query {
        status: string, optional
        page: integer, default(1)
        limit: integer, default(20)
    }

    returns: paginated(Task)
}

endpoint POST /tasks {
    description: "Create a new task"
    auth: required

    body {
        title: string, required
        description: text, optional
        priority: integer, default(1)
    }

    returns: Task
    on_success: emit(TaskCreated)
}

models.cai

// Define entities with typed fields and modifiers
entity User {
    description: "A user with authentication"

    id: uuid, primary, auto
    email: string, required, unique
    password_hash: string, required
    name: string, required
    role: enum(reader, author, admin), default(reader)

    // Audit fields - auto-managed
    created_at: timestamp, auto
    updated_at: timestamp, auto_update

    index: [email]
    index: [role]
}

entity Post {
    description: "A blog post with relationships"

    id: uuid, primary, auto
    title: string, required, searchable
    content: text, required, searchable
    author_id: ref(User), required
    tags: list(string), optional
    status: enum(draft, published), default(draft)

    // Soft delete support
    deleted_at: timestamp, optional, soft_delete

    index: [author_id, status]
}

auth.cai

// Configure JWT authentication
config {
    name: "secure-api"
    version: "1.0.0"

    auth: jwt {
        issuer: env(JWT_ISSUER)
        secret: env(JWT_SECRET)
        expiry: 24h
    }
}

// Login endpoint
endpoint POST /auth/login {
    description: "Authenticate user"
    auth: none

    body {
        email: string, required
        password: string, required
    }

    returns: {
        token: string
        user: User
        expires_at: timestamp
    }
}

// Protected endpoint with role-based access
endpoint DELETE /users/{id} {
    description: "Delete user (admin only)"
    auth: required
    roles: [admin]

    path { id: uuid, required }
    returns: void
}

workflows.cai

// Define multi-step workflows with Temporal
workflow ProcessOrder {
    trigger: OrderPlaced

    steps {
        validate_inventory {
            call: InventoryService.check {
                items: trigger.items
            }
            timeout: 10s
            on_fail: cancel
        }

        charge_payment {
            call: Stripe.charge {
                amount: trigger.total
                customer: trigger.customer_id
            }
            timeout: 30s
            retry: 3 times with exponential_backoff
            on_fail: rollback
        }

        ship_order {
            for_each: trigger.items
            call: ShippingService.create_label {
                item: current
                address: trigger.shipping_address
            }
        }

        send_confirmation {
            send: email(trigger.customer.email) {
                template: "order_confirmed"
                data: { order_id: trigger.id }
            }
        }
    }

    on_complete: emit(OrderFulfilled)
}

mongodb.cai

// MongoDB collections with embedded documents
config {
    database_type: "mongodb"
    mongodb_uri: "mongodb://localhost:27017"
    mongodb_database: "myapp"
}

database mongodb {
    collection User {
        _id: objectid, primary, auto
        email: string, required, unique
        username: string, required, unique

        // Embedded profile document
        profile: embedded {
            first_name: string, optional
            last_name: string, optional
            avatar_url: string, optional
        }

        is_active: bool, default(true)
        created_at: date, auto

        indexes {
            index: [email] unique
            index: [username] unique
        }
    }

    collection Product {
        _id: objectid, primary, auto
        sku: string, required, unique
        name: string, required
        price: double, required
        categories: array(string), optional

        // Nested embedded documents
        attributes: embedded {
            color: string, optional
            dimensions: embedded {
                length: double, optional
                width: double, optional
            }
        }

        indexes {
            index: [name] text
            index: [categories]
        }
    }
}

user-api.cai

// Complete User API with MongoDB + Endpoints
config {
    database_type: "mongodb"
    mongodb_uri: "mongodb://localhost:27017"
    mongodb_database: "codeai_test"
}

database mongodb {
    collection User {
        description: "User collection with basic profile"

        _id: objectid, primary, auto
        name: string, required
        email: string, required, unique
        age: int, optional
        is_active: bool, default(true)
        created_at: date, auto
        updated_at: date, auto

        indexes {
            index: [email] unique
            index: [created_at]
        }
    }
}

// Create a new user
endpoint POST "/users" {
    request CreateUserRequest from body
    response User status 201

    do {
        validate(request)
        insert("users", request)
        emit("user.created")
    }
}

// Get user by ID
endpoint GET "/users/:id" {
    request User from path
    response User status 200

    do {
        validate(id)
        query("users", id)
    }
}

// Get all users with pagination
endpoint GET "/users" {
    request SearchParams from query
    response UserList status 200

    do {
        query("users", "")
        paginate(20, 0)
    }
}

// Update user
endpoint PUT "/users/:id" {
    request UpdateUserRequest from body
    response User status 200

    do {
        validate(id)
        validate(request)
        update("users", id, request)
        emit("user.updated")
    }
}

// Partial update
endpoint PATCH "/users/:id" {
    request UpdateUserRequest from body
    response User status 200

    do {
        validate(id)
        patch("users", id, request)
    }
}

// Delete user
endpoint DELETE "/users/:id" {
    request User from path
    response Empty status 204

    do {
        validate(id)
        delete("users", id)
        emit("user.deleted")
    }
}

// Health check
endpoint GET "/health" {
    response HealthStatus status 200

    do {
        check_health()
    }
}

// Request/Response models
database mongodb {
    collection CreateUserRequest {
        name: string, required
        email: string, required
        age: int, optional
    }

    collection UpdateUserRequest {
        name: string, optional
        email: string, optional
        age: int, optional
        is_active: bool, optional
    }

    collection SearchParams {
        limit: int, optional
        offset: int, optional
        query: string, optional
    }

    collection UserList {
        users: array
        total: int
        page: int
    }

    collection Empty {
    }

    collection HealthStatus {
        status: string
        timestamp: date
    }
}

Test with curl:

# Create user
curl -X POST http://localhost:8080/users \
  -H "Content-Type: application/json" \
  -d '{"name":"John Doe","email":"john@example.com","age":30}'

# Get all users
curl http://localhost:8080/users

# Get user by ID
curl http://localhost:8080/users/507f1f77bcf86cd799439011

# Update user
curl -X PUT http://localhost:8080/users/507f1f77bcf86cd799439011 \
  -H "Content-Type: application/json" \
  -d '{"name":"Jane Doe","age":31}'

# Delete user
curl -X DELETE http://localhost:8080/users/507f1f77bcf86cd799439011

10x

Less boilerplate than traditional frameworks

Type-Safe

Validated at parse time with clear errors

LLM-Ready

Designed for AI code generation

Real-World Examples

Explore complete, production-ready examples. Each project demonstrates different CodeAI features and patterns.

Beginner

Hello World / Task Manager

A simple task/todo API demonstrating basic CRUD operations, authentication, and events.

Entity definitions with typed fields
REST endpoints for CRUD
JWT authentication
Event emission

~120

Lines .cai

vs

~800

Lines Go

85% less

entity Task {
  id: uuid, primary, auto
  title: string, required
  status: enum(pending, done)
  created_at: timestamp, auto
}

View Code

Intermediate

Blog API

Multi-entity blog platform with users, posts, comments, and categories with full RBAC.

Entity relationships (ref)
Role-based access (RBAC)
Soft delete support
Full-text search

~380

Lines .cai

vs

~3,200

Lines Go

88% less

entity Post {
  id: uuid, primary, auto
  title: string, searchable
  author_id: ref(User)
  deleted_at: timestamp, soft_delete
}

View Code

Advanced

E-commerce Backend

Complete order processing with products, cart, checkout workflow, and payment integration.

Order workflow (Temporal)
Saga pattern with rollback
Payment integration
Inventory management

~750

Lines .cai

vs

~6,500

Lines Go

88% less

workflow ProcessOrder {
  trigger: OrderPlaced
  steps {
    validate_inventory { ... }
    charge_payment { ... }
  }
}

View Code

Specialist

External Integrations

Resilient external API patterns with circuit breakers, webhooks, and GraphQL support.

Circuit breaker patterns
Retry with backoff
Webhook delivery
GraphQL integration

~610

Lines .cai

vs

~5,000

Lines Go

87% less

integration PaymentAPI {
  circuit_breaker: {
    threshold: 5 failures in 1m
    reset_after: 30s
  }
}

View Code

Specialist

Scheduled Jobs

Background job processing with cron scheduling, queues, retries, and monitoring.

Cron-based scheduling
Priority job queues
Report generation
Data maintenance tasks

~680

Lines .cai

vs

~5,400

Lines Go

87% less

job DailyReport {
  schedule: "0 6 * * *"
  queue: default
  timeout: 30m
  retry: 3 times
}

View Code

Browse All Examples on GitHub

Each example includes documentation, test scripts, and is fully runnable

Documentation

Explore the full documentation on GitHub

View Documentation

CodeAI Declarative Backend Framework for LLMs

Why CodeAI?

LLM-Friendly Syntax

Production Ready

Type Safe

Fault Tolerant

OpenAPI Generation

Enterprise Features

Zero Boilerplate

Open Source

How It Works

DSL Layer

Parser

Go Runtime

REST API

DSL Layer

Parser

Go Runtime

REST API

Get Started in Minutes

Install CodeAI

Create Your First .cai File

Start the Server

Test Your REST API

See It In Action

Real-World Examples

Hello World / Task Manager

Blog API

E-commerce Backend

External Integrations

Scheduled Jobs

Documentation