jean-philippe
3fae2fcbe1
This is the initial commit for the CODEX_ADK project, a full-stack AI agent management platform featuring: BACKEND (ASP.NET Core 8.0): - CQRS architecture with 6 commands and 7 queries - 16 API endpoints (all working and tested) - PostgreSQL database with 5 entities - AES-256 encryption for API keys - FluentValidation on all commands - Rate limiting and CORS configured - OpenAPI/Swagger documentation - Docker Compose setup (PostgreSQL + Ollama) FRONTEND (Flutter 3.x): - Dark theme with Svrnty branding - Collapsible sidebar navigation - CQRS API client with Result<T> error handling - Type-safe endpoints from OpenAPI schema - Multi-platform support (Web, iOS, Android, macOS, Linux, Windows) DOCUMENTATION: - Comprehensive API reference - Architecture documentation - Development guidelines for Claude Code - API integration guides - context-claude.md project overview Status: Backend ready (Grade A-), Frontend integration pending 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
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)
|