# 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
```bash
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)