CODEX_ADK/BACKEND/README.md

# Codex Backend API

CQRS-based ASP.NET Core 8.0 Web API using OpenHarbor.CQRS framework with PostgreSQL.

## Quick Start

```bash
# Build the solution
dotnet build

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

# API will be available at:
# - HTTP: http://localhost:5246
# - Swagger UI: http://localhost:5246/swagger (Development only)
```

## Documentation

### For Backend Developers
- **[CLAUDE.md](CLAUDE.md)** - Claude Code instructions and project standards
- **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** - System architecture and design decisions
- **[docs/CHANGELOG.md](docs/CHANGELOG.md)** - API breaking changes log
- **[docs/README.md](docs/README.md)** - API workflow and guidelines

### For Frontend Developers (Flutter)
- **[.claude-docs/FLUTTER-QUICK-START.md](.claude-docs/FLUTTER-QUICK-START.md)** - 5-minute quick start guide
- **[.claude-docs/FLUTTER-INTEGRATION.md](.claude-docs/FLUTTER-INTEGRATION.md)** - Complete integration guide
- **[docs/openapi.json](docs/openapi.json)** - Auto-generated OpenAPI specification

### For Claude Code
- **[.claude-docs/](.claude-docs/)** - Claude Code context and guidelines

## Project Structure

```
Codex/
├── Codex.Api/          # API layer, controllers (auto-generated), Program.cs
├── Codex.CQRS/         # Commands and Queries (business logic)
├── Codex.Dal/          # Data Access Layer, DbContext, entities
├── docs/               # API documentation and OpenAPI spec
└── .claude-docs/       # Development guidelines and Claude context
```

## Technology Stack

- **.NET 8.0 LTS** - Framework
- **ASP.NET Core 8.0** - Web API
- **OpenHarbor.CQRS 8.1.0** - CQRS framework (auto-generates REST endpoints)
- **PostgreSQL** - Database
- **Entity Framework Core 8.0** - ORM
- **FluentValidation** - Input validation
- **Swagger/OpenAPI** - API documentation

## CQRS Pattern

This API uses Command Query Responsibility Segregation (CQRS). Endpoints are **auto-generated** from C# classes:

- **Commands** (Write): `POST /api/command/{CommandName}`
- **Queries** (Read): `POST /api/query/{QueryName}` or `GET /api/query/{QueryName}`
- **Dynamic Queries** (Paginated): `POST /api/dynamicquery/{ItemType}`

Example:
```csharp
// Define a query
public record HealthQuery { }

// Automatically creates endpoint: POST /api/query/health
```

## API Documentation Workflow

### When Adding/Modifying APIs:

1. **Add XML documentation** to Commands/Queries:
```csharp
/// <summary>Creates a new user account</summary>
/// <param name="username">Unique username</param>
/// <response code="200">User created successfully</response>
/// <response code="400">Validation failed</response>
public record CreateUserCommand
{
    public string Username { get; init; } = string.Empty;
    public string Email { get; init; } = string.Empty;
}
```

2. **Build and export OpenAPI spec**:
```bash
dotnet build
./export-openapi.sh
```

3. **Update CHANGELOG.md** if breaking changes

4. **Commit and notify frontend team**:
```bash
git add .
git commit -m "Add CreateUser command with documentation"
git push
```

## Database Migrations

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

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

## Testing

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

## Environment Configuration

API configuration is managed through `appsettings.json` and `appsettings.Development.json`:

- **CORS**: Configure allowed origins in `Cors:AllowedOrigins`
- **Database**: Connection string in `ConnectionStrings:DefaultConnection`
- **Logging**: Console logging enabled in Development

## Key Features

- Auto-generated REST endpoints from CQRS classes
- Type-safe API contracts via OpenAPI
- Automatic input validation with FluentValidation
- XML documentation integrated with Swagger
- PostgreSQL with EF Core migrations
- CORS configuration via appsettings
- Bearer token authentication support (documented, not yet implemented)

## Contributing

1. Follow patterns in `CLAUDE.md`
2. Add XML documentation to all Commands/Queries
3. Use `.AsNoTracking()` for all read queries
4. Regenerate OpenAPI spec after changes
5. Update CHANGELOG.md for breaking changes

## Support

- **Swagger UI**: http://localhost:5246/swagger
- **OpenAPI Spec**: `docs/openapi.json`
- **Architecture Docs**: `docs/ARCHITECTURE.md`
- **Issues**: [GitHub Issues](your-repo-url)

---

**Version**: 1.0
**API Version**: v1
**OpenAPI**: 3.0.1
**Last Updated**: 2025-01-26