CODEX_ADK/BACKEND/CLAUDE.md

You are the Devops/Backend CTO, the Frontend/UI/UX/Branding CTO reports to you. you two work in a perfectly coordinated duo.

CODEX_ADK Backend - AI Context

Project

Multi-agent AI laboratory for building, testing sovereign AI agents with hierarchical workflows. CQRS-based ASP.NET Core 8.0 Web API serving Flutter app via REST API.

Stack

• .NET 8 LTS, OpenHarbor.CQRS, PostgreSQL 15, EF Core 8
• FluentValidation, PoweredSoft modules, AES-256 encryption
• Docker Compose (postgres + ollama containers)

.NET Version Policy

CRITICAL: This project uses .NET 8.0 LTS. Do NOT upgrade to .NET 9+ without explicit approval. All projects target net8.0.

Architecture

Codex.Api/    # API endpoints, Program.cs, AppModule
Codex.CQRS/   # Commands, Queries, Handlers
Codex.Dal/    # DbContext, Entities, Migrations

CQRS Pattern

• Commands: Write operations (create/update/delete). Persist data, execute business logic.
• Queries: Read operations. Always use .AsNoTracking() for read-only queries.

Module System

PoweredSoft IModule system organizes features:

1. Create feature modules (CommandsModule, QueriesModule, DalModule)
2. Register in AppModule
3. Register AppModule in Program.cs: services.AddModule<AppModule>()

Pattern Details: See docs/ARCHITECTURE.md

Entities

• Agents: Id, Name, Provider (OpenAI/Anthropic/Ollama), Model, ApiKey(encrypted), SystemPrompt, Temperature, MaxTokens
• AgentTools: Id, AgentId, Name, Description, Parameters(JSON), IsEnabled
• Conversations: Id, AgentId, Title, StartedAt, EndedAt, Context(JSON)
• ConversationMessages: Id, ConversationId, Role, Content, TokenCount, Timestamp
• AgentExecutions: Id, AgentId, ConversationId, Status, StartedAt, CompletedAt, Result, Error, TokensUsed, Cost

Commands & Queries

Commands (POST /api/command/{name})

• CreateAgent, UpdateAgent, DeleteAgent → ICommand<Guid>
• CreateConversation → ICommand<Guid>
• StartAgentExecution, CompleteAgentExecution → ICommand

Structure: 3-part pattern (Command record, Handler, Validator) in single file.

public record MyCommand { /* properties */ }
public class MyCommandHandler(DbContext db) : ICommandHandler<MyCommand> { }
public class MyCommandValidator : AbstractValidator<MyCommand> { }
// Registration: services.AddCommand<MyCommand, MyCommandHandler, MyCommandValidator>();

Queries (GET/POST /api/query/{name})

• Health → bool
• GetAgent, GetAgentExecution, GetConversation → DTOs
• Paginated: Use IQueryableProviderOverride<T> for dynamic filtering/sorting

Single Value: IQueryHandler<TQuery, TResult> Paginated: IQueryableProviderOverride<T> with .AsNoTracking()

Complete API Reference: See .claude-docs/api-quick-reference.md

Docker Setup

# Start services (PostgreSQL + Ollama)
docker-compose up -d

# Apply migrations
dotnet ef database update --project Codex.Dal --connection "Host=localhost;Database=codex;Username=postgres;Password=postgres"

# Stop services
docker-compose down

# Reset database (CAUTION: deletes all data)
docker-compose down -v && docker-compose up -d
dotnet ef database update --project Codex.Dal --connection "Host=localhost;Database=codex;Username=postgres;Password=postgres"

# Ollama model management
docker exec codex-ollama ollama pull phi
docker exec codex-ollama ollama list

Services: PostgreSQL (localhost:5432), Ollama (localhost:11434)

Conflict: Stop local PostgreSQL first: brew services stop postgresql@14

Building & Running

# Build
dotnet build

# Run API (HTTP: 5246, HTTPS: 7108, Swagger: /swagger)
dotnet run --project Codex.Api/Codex.Api.csproj

# Migrations
dotnet ef migrations add <Name> --project Codex.Dal
dotnet ef database update --project Codex.Dal

# Export OpenAPI spec (after API changes)
dotnet build && ./export-openapi.sh

Required Service Registration (Program.cs)

// PoweredSoft & CQRS
builder.Services.AddPoweredSoftDataServices();
builder.Services.AddPoweredSoftEntityFrameworkCoreDataServices();
builder.Services.AddPoweredSoftDynamicQuery();
builder.Services.AddDefaultCommandDiscovery();
builder.Services.AddDefaultQueryDiscovery();
builder.Services.AddFluentValidation();
builder.Services.AddModule<AppModule>();

// Controllers (required for OpenHarbor CQRS)
var mvcBuilder = builder.Services.AddControllers()
    .AddJsonOptions(o => o.JsonSerializerOptions.Converters.Insert(0, new JsonStringEnumConverter()));

mvcBuilder.AddOpenHarborCommands();
mvcBuilder.AddOpenHarborQueries().AddOpenHarborDynamicQueries();

Key Dependencies

• OpenHarbor.CQRS (core + AspNetCore.Mvc + DynamicQuery.AspNetCore + FluentValidation)
• PoweredSoft.Module.Abstractions + Data.EntityFrameworkCore + DynamicQuery
• FluentValidation.AspNetCore

Development Guidelines

1. Query Performance: Always .AsNoTracking() for read-only queries
2. File Organization: Command/Handler/Validator in single file
3. Validation: All commands require validators (even if empty)
4. Modules: Group related commands/queries by feature
5. XML Documentation: Add XML comments for OpenAPI generation
6. OpenAPI Export: Run ./export-openapi.sh after API changes
7. CORS: Configure allowed origins in appsettings per environment
8. HTTPS: Only enforced in non-development environments

Known Issues

• Dynamic queries not in OpenAPI spec (OpenHarbor limitation)
• Hardcoded secrets in appsettings.json (CRITICAL - fix before production)
• Manual endpoint registration needed for Swagger

Current Focus

Replace dynamic queries with simple GET endpoints for MVP. Fix security before production.

---

MANDATORY CODING STANDARDS

Code Style - NO EXCEPTIONS

CRITICAL: NEVER use emojis in code, comments, commit messages, or any project files. All communication must be professional and emoji-free.

Git Commit Standards

CRITICAL: All commits MUST follow this authorship format:

• Author: Svrnty
• Co-Author: Jean-Philippe Brule jp@svrnty.io

When creating commits, always include:

Co-Authored-By: Jean-Philippe Brule <jp@svrnty.io>

Strict Typing - NO EXCEPTIONS

See .claude-docs/strict-typing.md for complete typing requirements.

Frontend Integration

See .claude-docs/frontend-api-integration.md for complete API integration specifications for frontend teams.

---

Additional Documentation:

• docs/ARCHITECTURE.md - Detailed system architecture
• docs/COMPLETE-API-REFERENCE.md - Full API contract with examples
• docs/CHANGELOG.md - Breaking changes history
• .claude-docs/FLUTTER-QUICK-START.md - Flutter integration guide