codeai

CodeAI

A Go-based runtime for defining and executing AI agent specifications using a declarative domain-specific language (DSL). CodeAI provides a structured approach to building backend services with built-in support for databases, authentication, workflows, jobs, events, and integrations.

Table of Contents

• Overview
• Quick Start
• Features
• DSL Example
• Architecture
• Requirements
• Installation
• Development
• Deployment
• Documentation
• License

Overview

CodeAI is a declarative backend framework that allows developers and LLMs to define entire backend services using a simple, readable DSL. Instead of writing boilerplate code for APIs, database schemas, authentication, and background jobs, you describe what you want and CodeAI generates the runtime.

Key Benefits

• Declarative DSL: Define entities, endpoints, workflows, and jobs in a human-readable format
• LLM-Friendly: Designed to be easily understood and generated by AI assistants
• Production-Ready Infrastructure: Built-in auth, caching, circuit breakers, retry logic, and observability
• Type-Safe: Full validation at parse time with detailed error messages
• Extensible: Modular architecture with pluggable integrations

Target Audience

• LLM Agents: Generate complete backend specifications programmatically
• Backend Developers: Rapidly prototype and build production services
• DevOps Engineers: Deploy standardized, observable microservices
• Startups: Accelerate time-to-market with minimal boilerplate

Project Status

Version: 1.0 | Status: 90% Complete

Quick Start

One-Line Installation

go install github.com/bargom/codeai/cmd/codeai@latest

Or Build from Source

git clone https://github.com/bargom/codeai.git
cd codeai
make build
./bin/codeai version

Basic Usage

# Parse a DSL file
./bin/codeai parse myapp.cai

# Validate syntax
./bin/codeai validate myapp.cai

# Start the API server
./bin/codeai server start --db-name codeai

# Generate shell completions
./bin/codeai completion bash > /etc/bash_completion.d/codeai

Full Quick Start Guide

Features

DSL Language

Define your backend with a clean, declarative syntax:

Backend Modules

Built-In Patterns

Observability

OpenAPI Generation

Automatic OpenAPI 3.0 specification generation from your DSL definitions.

DSL Example

Simple Application

// myapp.cai - Configuration Example

var appName = "MyService"
var environment = "production"
var maxConnections = 100

// Feature flags
var features = ["auth", "caching", "metrics"]
var debugMode = false

// Process each feature
for feature in features {
    var current = feature
}

// Conditional configuration
if debugMode {
    var logLevel = "debug"
} else {
    var logLevel = "info"
}

// Initialize service
exec {
    echo "Starting $appName in $environment"
}

Parse and Validate

# Parse to JSON AST
./bin/codeai parse --output json myapp.cai

# Validate syntax and semantics
./bin/codeai validate myapp.cai

API Interaction

# Health check
curl http://localhost:8080/health

# Create a configuration
curl -X POST http://localhost:8080/configs \
  -H "Content-Type: application/json" \
  -d '{"name": "myapp", "content": "var x = 1"}'

# List configurations
curl http://localhost:8080/configs

# Execute a deployment
curl -X POST http://localhost:8080/deployments/UUID/execute

Architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                              HTTP Layer                                  │
│  ┌───────────────────────────────────────────────────────────────────┐  │
│  │              Chi Router + Middleware Stack                         │  │
│  │  (RequestID, RealIP, Logger, Recoverer, Timeout, JSON)            │  │
│  └───────────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                    ┌───────────────┼───────────────┐
                    ▼               ▼               ▼
            ┌───────────┐   ┌───────────┐   ┌───────────┐
            │   Auth    │   │  Handlers │   │  OpenAPI  │
            │Middleware │   │  (CRUD)   │   │   Docs    │
            └───────────┘   └───────────┘   └───────────┘
                                    │
┌─────────────────────────────────────────────────────────────────────────┐
│                        Business Logic Layer                              │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐               │
│  │  Parser  │  │ Workflow │  │Scheduler │  │ Validator│               │
│  │  (DSL)   │  │(Temporal)│  │ (Asynq)  │  │          │               │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘               │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
┌─────────────────────────────────────────────────────────────────────────┐
│                       Infrastructure Layer                               │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐               │
│  │ Database │  │  Event   │  │  Cache   │  │Integration│               │
│  │(Postgres)│  │   Bus    │  │ (Redis)  │  │(REST/GQL)│               │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘               │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
┌─────────────────────────────────────────────────────────────────────────┐
│                      Cross-Cutting Concerns                              │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐               │
│  │ Logging  │  │ Metrics  │  │  Health  │  │ Shutdown │               │
│  │ (slog)   │  │(Promethe)│  │  Checks  │  │ Graceful │               │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘               │
└─────────────────────────────────────────────────────────────────────────┘

Directory Structure

codeai/
├── cmd/codeai/           # CLI entry point (Cobra commands)
│   └── cmd/              # parse, validate, server, deploy, config
├── internal/             # Private application code
│   ├── api/              # HTTP handlers, router, server
│   ├── ast/              # Abstract Syntax Tree definitions
│   ├── auth/             # JWT validation, JWKS, middleware
│   ├── cache/            # Redis and memory caching
│   ├── database/         # PostgreSQL, migrations, repositories
│   ├── event/            # Event bus and dispatching
│   ├── health/           # Health check endpoints
│   ├── openapi/          # OpenAPI specification generation
│   ├── pagination/       # Pagination utilities
│   ├── parser/           # DSL lexer and parser (Participle)
│   ├── query/            # Query builder and executor
│   ├── rbac/             # Role-based access control
│   ├── scheduler/        # Asynq job scheduler
│   ├── shutdown/         # Graceful shutdown handling
│   ├── validation/       # Input validation middleware
│   ├── validator/        # AST validation
│   ├── webhook/          # Webhook delivery system
│   └── workflow/         # Temporal workflow orchestration
├── pkg/                  # Public libraries
│   ├── integration/      # REST, GraphQL clients, circuit breaker
│   ├── logging/          # Structured logging utilities
│   ├── metrics/          # Prometheus metrics
│   └── types/            # Shared type definitions
├── config/               # Configuration files (YAML)
├── docs/                 # Documentation
└── test/                 # Integration and performance tests

Requirements

Required

Optional

Verify Installation

go version          # go1.24.0 or higher
psql --version      # PostgreSQL 14.x or higher
make --version      # GNU Make 3.81 or higher

Installation

From Source

# Clone repository
git clone https://github.com/bargom/codeai.git
cd codeai

# Install dependencies
go mod download

# Build binary
make build

# Verify installation
./bin/codeai version
./bin/codeai --help

Database Setup

# Create database
createdb codeai

# Run migrations
./bin/codeai server migrate --db-name codeai --db-user postgres

# Or with custom settings
./bin/codeai server migrate \
  --db-host localhost \
  --db-port 5432 \
  --db-name codeai \
  --db-user codeai_user \
  --db-password secret

Development

Running Tests

# All tests with race detector
make test

# Unit tests only
make test-unit

# Integration tests (requires PostgreSQL)
make test-integration

# CLI integration tests
make test-cli

# Coverage report
make test-coverage
# Open coverage.html in browser

Running Benchmarks

# All benchmarks
make bench

# Parser benchmarks
make bench-parse

# Validator benchmarks
make bench-validate

Code Quality

# Run linter
make lint

# Tidy dependencies
make tidy

# Clean build artifacts
make clean

Available Make Targets

Contributing

See CONTRIBUTING.md for guidelines on:

• Code style and conventions
• Pull request process
• Testing requirements
• Documentation standards

Deployment

Docker

# Dockerfile
FROM golang:1.24-alpine AS builder
WORKDIR /app
COPY . .
RUN go build -ldflags "-s -w" -o codeai ./cmd/codeai

FROM alpine:latest
RUN apk --no-cache add ca-certificates
WORKDIR /app
COPY --from=builder /app/codeai .
EXPOSE 8080
CMD ["./codeai", "server", "start"]

# Build and run
docker build -t codeai:latest .
docker run -p 8080:8080 \
  -e CODEAI_DB_HOST=host.docker.internal \
  -e CODEAI_DB_NAME=codeai \
  codeai:latest

Kubernetes

# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: codeai
spec:
  replicas: 3
  selector:
    matchLabels:
      app: codeai
  template:
    metadata:
      labels:
        app: codeai
    spec:
      containers:
      - name: codeai
        image: codeai:latest
        ports:
        - containerPort: 8080
        env:
        - name: CODEAI_DB_HOST
          valueFrom:
            secretKeyRef:
              name: codeai-secrets
              key: db-host
        - name: CODEAI_DB_PASSWORD
          valueFrom:
            secretKeyRef:
              name: codeai-secrets
              key: db-password
        livenessProbe:
          httpGet:
            path: /health
            port: 8080
          initialDelaySeconds: 5
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /ready
            port: 8080
          initialDelaySeconds: 5
          periodSeconds: 5
---
apiVersion: v1
kind: Service
metadata:
  name: codeai
spec:
  selector:
    app: codeai
  ports:
  - port: 80
    targetPort: 8080
  type: ClusterIP

Full Deployment Guide

Documentation

Environment Variables

License

This project is licensed under the MIT License - see the LICENSE file for details.

MIT License

Copyright (c) 2026 bargom

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

Acknowledgments

Built with excellent open-source projects:

• Participle - Parser combinator library
• Chi - HTTP router
• Temporal - Workflow orchestration
• Asynq - Distributed task queue
• go-redis - Redis client
• Prometheus - Metrics and monitoring

CodeAI - Declarative Backend Development
GitHub | Quick Start | API Docs