CODEX_ADK/BACKEND/README.md

Codex Backend API

CQRS-based ASP.NET Core 8.0 Web API using OpenHarbor.CQRS framework with PostgreSQL.

Quick Start

# Build the solution
dotnet build

# Run the API
dotnet run --project Codex.Api/Codex.Api.csproj

# API will be available at:
# - HTTP: http://localhost:5246
# - Swagger UI: http://localhost:5246/swagger (Development only)

Documentation

For Backend Developers

• CLAUDE.md - Claude Code instructions and project standards
• docs/ARCHITECTURE.md - System architecture and design decisions
• docs/CHANGELOG.md - API breaking changes log
• docs/README.md - API workflow and guidelines

For Frontend Developers (Flutter)

• .claude-docs/FLUTTER-QUICK-START.md - 5-minute quick start guide
• .claude-docs/FLUTTER-INTEGRATION.md - Complete integration guide
• docs/openapi.json - Auto-generated OpenAPI specification

For Claude Code

• .claude-docs/ - Claude Code context and guidelines

Project Structure

Codex/
├── Codex.Api/          # API layer, controllers (auto-generated), Program.cs
├── Codex.CQRS/         # Commands and Queries (business logic)
├── Codex.Dal/          # Data Access Layer, DbContext, entities
├── docs/               # API documentation and OpenAPI spec
└── .claude-docs/       # Development guidelines and Claude context

Technology Stack

• .NET 8.0 LTS - Framework
• ASP.NET Core 8.0 - Web API
• OpenHarbor.CQRS 8.1.0 - CQRS framework (auto-generates REST endpoints)
• PostgreSQL - Database
• Entity Framework Core 8.0 - ORM
• FluentValidation - Input validation
• Swagger/OpenAPI - API documentation

CQRS Pattern

This API uses Command Query Responsibility Segregation (CQRS). Endpoints are auto-generated from C# classes:

• Commands (Write): POST /api/command/{CommandName}
• Queries (Read): POST /api/query/{QueryName} or GET /api/query/{QueryName}
• Dynamic Queries (Paginated): POST /api/dynamicquery/{ItemType}

Example:

// Define a query
public record HealthQuery { }

// Automatically creates endpoint: POST /api/query/health

API Documentation Workflow

When Adding/Modifying APIs:

1. Add XML documentation to Commands/Queries:

/// <summary>Creates a new user account</summary>
/// <param name="username">Unique username</param>
/// <response code="200">User created successfully</response>
/// <response code="400">Validation failed</response>
public record CreateUserCommand
{
    public string Username { get; init; } = string.Empty;
    public string Email { get; init; } = string.Empty;
}

2. Build and export OpenAPI spec:

dotnet build
./export-openapi.sh

3. Update CHANGELOG.md if breaking changes

4. Commit and notify frontend team:

git add .
git commit -m "Add CreateUser command with documentation"
git push

Database Migrations

# Add a new migration
dotnet ef migrations add <MigrationName> --project Codex.Dal

# Update database
dotnet ef database update --project Codex.Dal

Testing

# Run tests (when test projects are added)
dotnet test

Environment Configuration

API configuration is managed through appsettings.json and appsettings.Development.json:

• CORS: Configure allowed origins in Cors:AllowedOrigins
• Database: Connection string in ConnectionStrings:DefaultConnection
• Logging: Console logging enabled in Development

Key Features

• Auto-generated REST endpoints from CQRS classes
• Type-safe API contracts via OpenAPI
• Automatic input validation with FluentValidation
• XML documentation integrated with Swagger
• PostgreSQL with EF Core migrations
• CORS configuration via appsettings
• Bearer token authentication support (documented, not yet implemented)

Contributing

1. Follow patterns in CLAUDE.md
2. Add XML documentation to all Commands/Queries
3. Use .AsNoTracking() for all read queries
4. Regenerate OpenAPI spec after changes
5. Update CHANGELOG.md for breaking changes

Support

• Swagger UI: http://localhost:5246/swagger
• OpenAPI Spec: docs/openapi.json
• Architecture Docs: docs/ARCHITECTURE.md
• Issues: GitHub Issues

---

Version: 1.0 API Version: v1 OpenAPI: 3.0.1 Last Updated: 2025-01-26