CODEX_ADK/BACKEND/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Codex is a CQRS-based ASP.NET Core 8.0 Web API using the OpenHarbor.CQRS framework with a modular architecture powered by PoweredSoft modules.

.NET Version Policy

IMPORTANT: This project uses .NET 8.0 LTS and should NOT be upgraded to .NET 9 or later versions without explicit approval. All projects must target net8.0.

Docker Setup (Recommended)

This project uses Docker containers for PostgreSQL and Ollama:

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

# Verify containers are running
docker ps

# Apply database 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"

Services:

• PostgreSQL: localhost:5432 (codex/postgres/postgres)
• Ollama: localhost:11434

Important: If you have a local PostgreSQL running on port 5432, stop it first:

brew services stop postgresql@14  # or your PostgreSQL version

Ollama Model Management

# Pull a lightweight model for testing (1.6GB)
docker exec codex-ollama ollama pull phi

# List downloaded models
docker exec codex-ollama ollama list

# Test Ollama is working
curl http://localhost:11434/api/tags

Building and Running

# Build the solution
dotnet build

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

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

The API runs on:

• HTTP: http://localhost:5246
• HTTPS: https://localhost:7108
• Swagger UI (Development only): http://localhost:5246/swagger

Architecture

CQRS Pattern

This application strictly follows the Command Query Responsibility Segregation (CQRS) pattern:

• Commands: Handle write operations (create, update, delete). Execute business logic and persist data.
• Queries: Handle read operations. Always use .AsNoTracking() for read-only operations.

Module System

The application uses PoweredSoft's module system (IModule) to organize features. Each module registers its services in the ConfigureServices method.

Module Registration Flow:

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

Project Structure

• Codex.Api: API layer with controllers, Program.cs, and AppModule
• Codex.CQRS: Commands, queries, and business logic
• Codex.Dal: Data access layer with DbContext, entities, and query provider infrastructure

Commands

Commands perform write operations and follow a strict 3-part structure:

1. Command Definition (record)

public record MyCommand
{
    // Properties
}

2. Handler Implementation (implements ICommandHandler<TCommand>)

public class MyCommandHandler(DbContext dbContext) : ICommandHandler<MyCommand>
{
    public async Task HandleAsync(MyCommand command, CancellationToken cancellationToken = default)
    {
        // Business logic
    }
}

3. Validation (extends AbstractValidator<TCommand>)

public class MyCommandValidator : AbstractValidator<MyCommand>
{
    public MyCommandValidator()
    {
        // FluentValidation rules
    }
}

Registration: All three components go in a single file and are registered together:

services.AddCommand<MyCommand, MyCommandHandler, MyCommandValidator>();

Queries

Single Value Queries

Return a specific value (e.g., health check, lookup):

public record MyQuery { }

public class MyQueryHandler : IQueryHandler<MyQuery, TResult>
{
    public Task<TResult> HandleAsync(MyQuery query, CancellationToken cancellationToken = default)
    {
        // Return single value
    }
}

// Registration
services.AddQuery<MyQuery, TResult, MyQueryHandler>();

Paginated Queries

Return queryable lists with automatic filtering, sorting, pagination, and aggregates:

// 1. Define the item structure
public record MyQueryItem
{
    // Properties for each list item
}

// 2. Implement IQueryableProviderOverride<T>
public class MyQueryableProvider(DbContext dbContext) : IQueryableProviderOverride<MyQueryItem>
{
    public Task<IQueryable<MyQueryItem>> GetQueryableAsync(object query, CancellationToken cancellationToken = default)
    {
        var result = dbContext.MyTable
            .AsNoTracking() // ALWAYS use AsNoTracking for queries
            .Select(x => new MyQueryItem { /* mapping */ });

        return Task.FromResult(result);
    }
}

// Registration
services.AddDynamicQuery<MyQueryItem>()
    .AddQueryableProviderOverride<MyQueryItem, MyQueryableProvider>();

IMPORTANT: Paginated queries return IQueryable<T>. The framework handles actual query execution, pagination, filtering, and sorting.

Data Access Layer Setup

The DAL requires specific infrastructure files for the CQRS query system to work properly:

Required Files

1. IQueryableProviderOverride.cs: Interface for custom query providers
2. ServiceCollectionExtensions.cs: Extension to register query provider overrides
3. DefaultQueryableProvider.cs: Default provider that checks for overrides
4. InMemoryQueryableHandlerService.cs: Handler for in-memory queryables
5. DalModule.cs: Module to register DAL services

All code examples for these files are in .context/dal-context.md.

DbContext

Create your DbContext with EF Core and use migrations for schema management:

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

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

OpenAPI Documentation Export

After adding or modifying commands/queries with XML documentation:

# Build and export OpenAPI specification
dotnet build
./export-openapi.sh

# This generates docs/openapi.json for frontend integration

API Configuration (Program.cs)

Required service registrations:

// PoweredSoft & CQRS
builder.Services.AddPoweredSoftDataServices();
builder.Services.AddPoweredSoftEntityFrameworkCoreDataServices();
builder.Services.AddPoweredSoftDynamicQuery();
builder.Services.AddDefaultCommandDiscovery();
builder.Services.AddDefaultQueryDiscovery();

// Validation
builder.Services.AddFluentValidation();

// Module registration
builder.Services.AddModule<AppModule>();

// Controllers with OpenHarbor CQRS integration
var mvcBuilder = builder.Services
    .AddControllers()
    .AddJsonOptions(jsonOptions =>
    {
        jsonOptions.JsonSerializerOptions.Converters.Insert(0, new JsonStringEnumConverter());
    });

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

Note: Controllers (not minimal APIs) are required for OpenHarbor CQRS integration.

Key Dependencies

• OpenHarbor.CQRS: CQRS framework core
• OpenHarbor.CQRS.AspNetCore.Mvc: MVC integration for commands/queries
• OpenHarbor.CQRS.DynamicQuery.AspNetCore: Dynamic query support
• OpenHarbor.CQRS.FluentValidation: FluentValidation integration
• PoweredSoft.Module.Abstractions: Module system
• PoweredSoft.Data.EntityFrameworkCore: Data access abstractions
• PoweredSoft.DynamicQuery: Dynamic query engine
• FluentValidation.AspNetCore: Validation

Development Guidelines

1. Query Performance: Always use .AsNoTracking() for read-only queries
2. File Organization: Place command/handler/validator in the same file
3. Validation: All commands must have validators (even if empty)
4. Modules: Group related commands/queries into feature modules
5. XML Documentation: Add XML comments to all commands/queries for OpenAPI generation
6. OpenAPI Export: Run ./export-openapi.sh after API changes to update frontend specs
7. CORS: Configure allowed origins in appsettings for different environments
8. HTTPS: Only enforced in non-development environments

🔒 MANDATORY CODING STANDARDS

Strict Typing - NO EXCEPTIONS

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

---

🗣️ Response Protocol

See .claude-docs/response-protocol.md for complete protocol details.

---

📡 Frontend Integration

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