CODEX_ADK/BACKEND/docs/ARCHITECTURE.md

Codex API Architecture

Overview

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

Key Design Decisions

CQRS Pattern with OpenHarbor

• Auto-generated REST endpoints: Commands and Queries are automatically exposed as REST endpoints by the OpenHarbor.CQRS framework
• Convention-based routing:
  • Commands: POST /api/command/{CommandName}
  • Queries: POST /api/query/{QueryName}
  • Dynamic Queries: POST /api/dynamicquery/{QueryItemType}
• Command/Query Segregation: Write operations (Commands) are strictly separated from read operations (Queries)

Module System

• Feature-based organization using PoweredSoft's IModule interface
• Modules provide clean separation of concerns and dependency registration
• Module hierarchy: AppModule → DalModule, CommandsModule, QueriesModule

Data Access

• Entity Framework Core with PostgreSQL
• Query optimization: All read operations use .AsNoTracking() for better performance
• Dynamic queries with automatic filtering, sorting, and pagination via PoweredSoft.DynamicQuery

Validation

• FluentValidation integration for all commands
• Automatic validation pipeline before command execution
• All commands require a validator (even if empty)

API Documentation

• OpenAPI/Swagger as single source of truth
• XML documentation for all Commands, Queries, and DTOs
• Auto-generated API contract exported to docs/openapi.json

Project Structure

Codex.sln
├── Codex.Api/          # API layer, Program.cs, AppModule
├── Codex.CQRS/         # Commands and Queries
│   ├── Commands/       # Write operations
│   └── Queries/        # Read operations
├── Codex.Dal/          # Data access layer
│   ├── CodexDbContext  # EF Core DbContext
│   ├── Entities/       # Database entities
│   └── Infrastructure/ # Query provider overrides
└── docs/               # API documentation
    ├── openapi.json    # Auto-generated OpenAPI spec
    ├── ARCHITECTURE.md # This file
    └── CHANGELOG.md    # Breaking changes log

Technology Stack

Core Framework

• .NET 8.0 LTS
• ASP.NET Core 8.0
• OpenHarbor.CQRS 8.1.0-rc1

Data Access

• Entity Framework Core 8.0
• Npgsql (PostgreSQL provider)
• PoweredSoft.Data & PoweredSoft.DynamicQuery

Validation & Documentation

• FluentValidation 11.3+
• Swashbuckle.AspNetCore (Swagger)
• XML documentation generation

Security & Authentication

Planned Features

• JWT Bearer token authentication
• Role-based authorization
• CORS configuration for specific origins

Current State

• Authentication infrastructure documented in OpenAPI spec
• Implementation pending

Performance Considerations

Query Optimization

• .AsNoTracking() for all read operations
• Pagination support for large datasets
• Dynamic filtering to reduce data transfer

Caching Strategy

• In-memory caching available via IMemoryCache
• Cache implementation per use case

Deployment

Environment Configuration

• Development: Swagger UI enabled, relaxed CORS
• Production: HTTPS enforcement, restricted CORS, no Swagger UI

Database Migrations

dotnet ef migrations add <MigrationName> --project Codex.Dal
dotnet ef database update --project Codex.Dal

API Contract Management

Workflow

1. Update Command/Query with XML documentation
2. Build solution to generate XML files
3. Run export-openapi.sh to export OpenAPI spec
4. Frontend teams consume docs/openapi.json

Breaking Changes

All breaking API changes must be documented in CHANGELOG.md with:

• Date of change
• Affected endpoints
• Migration guide
• Version number (when versioning is implemented)

Future Enhancements

• API versioning strategy
• Real-time features (SignalR)
• Advanced caching layer
• Distributed tracing
• Health checks endpoint (beyond basic health query)