229a0698a3
Multi-agent AI laboratory with ASP.NET Core 8.0 backend and Flutter frontend. Implements CQRS architecture, OpenAPI contract-first API design. BACKEND: Agent management, conversations, executions with PostgreSQL + Ollama FRONTEND: Cross-platform UI with strict typing and Result-based error handling Co-Authored-By: Jean-Philippe Brule <jp@svrnty.io>
126 lines
3.9 KiB
Markdown
126 lines
3.9 KiB
Markdown
# 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)
|