Development

Use this section when you are contributing to AxonFlow itself or validating platform behavior locally before building against the SDKs. The goal is not only to make the code compile, but to reproduce the real request path, policy behavior, connector flows, and monitoring surfaces that end users will rely on.

Development Guides

Guide	Description
Local Development	Set up AxonFlow locally with Docker Compose
Testing Overview	Testing strategies and best practices
Load Testing	Performance and load testing methodology
Performance Testing	Benchmark and optimize your deployment

Quick Start

Prerequisites

• Docker and Docker Compose
• Go 1.25 for the main platform workflows and local contributor setup
• Node.js 18+ for frontend and docs-related tooling

Some examples in the repository still declare older Go versions in their own go.mod files. For platform development and CI parity, follow the repo workflows and use Go 1.25.

Local Setup

# Clone the repository
git clone https://github.com/getaxonflow/axonflow.git
cd axonflow

# Start all services
docker compose up -d

# Verify services are healthy
docker compose ps
curl -sf http://localhost:8080/health | jq .
curl -sf http://localhost:8081/health | jq .

Service Endpoints

Service	URL	Description
Agent	http://localhost:8080	Request validation, system policies, MCP, and audit entry point
Orchestrator	http://localhost:8081	Tenant policies, provider routing, workflows, and MAP
Prometheus	http://localhost:9090	Metrics
Grafana	http://localhost:3000	Dashboards

The fastest sanity check for local development is to verify:

• the Agent accepts traffic on POST /api/request
• the Orchestrator is healthy and can bootstrap providers
• Prometheus can scrape /prometheus
• Grafana is reachable before you start chasing a latency or workflow bug

Testing

Unit Tests

# Run all tests
go test ./platform/...

# Run with coverage
go test ./platform/... -cover

# Run specific package
go test ./platform/agent/...
go test ./platform/orchestrator/...

For most feature work, start with a focused package and only then fan out to the broader test suites. That gives faster feedback and makes failures easier to reason about.

Integration Tests

# Start test environment
docker compose up -d

# Run integration tests
go test ./platform/... -tags=integration

note

For community development, use docker compose up -d to start the test environment. The docker-compose.test.yml file is available in the enterprise repository.

The integration environment matters because many AxonFlow bugs only appear when PostgreSQL, Redis, monitoring, and HTTP request paths are live together. If you are touching policies, connectors, workflows, or request routing, do not rely on unit tests alone.

What Good Local Development Looks Like

A productive local setup lets you do all of the following:

• reproduce real /api/request behavior
• debug MCP requests against real or representative backends
• inspect policy and workflow effects in logs and metrics
• verify SDK or API examples against the running runtime
• compare community behavior with the limits and workflows described in the docs

That is the level of confidence a staff engineer usually wants before changing platform behavior or documenting a new integration path.

Project Structure

axonflow/
├── platform/
│   ├── agent/          # Policy enforcement agent
│   ├── orchestrator/   # Multi-agent planning and workflow execution
│   ├── connectors/     # MCP connectors
│   └── shared/         # Shared libraries
├── config/             # Configuration files
├── migrations/         # Database migrations
├── examples/           # SDK and integration examples
├── scripts/            # Build and utility scripts
├── docs/               # Product documentation
└── docker-compose.yml  # Local development

For most contributors, the most relevant directories are:

• platform/agent for system-policy enforcement, MCP, gateway-mode flows, and audit entry points
• platform/orchestrator for provider routing, workflow execution, tenant-policy logic, and MAP
• platform/test for broader integration expectations
• config/ and docker-compose*.yml for local runtime behavior

Next Steps

• Set up Local Development environment
• Review the Testing Overview
• Run Load Testing to benchmark performance
• See Contributing to contribute back