CODEX_ADK/context-claude.md

CODEX_ADK - Project Context for Claude

Last Updated: 2025-10-26 Project Status: MVP v1.0.0 - Backend Ready, Frontend Integration Pending Grade: A- (Backend), Development Phase (Frontend)

---

Project Overview

CODEX_ADK (Codex API Development Kit) is a full-stack AI agent management platform called Svrnty Console. It's a sophisticated control panel for managing AI agents with support for multiple model providers (OpenAI, Anthropic, Ollama).

Core Purpose

• Manage AI agents with dynamic model configuration
• Track conversations and execution history
• Support multiple model providers with encrypted API keys
• Provide a modern, responsive UI for agent management

---

Architecture at a Glance

┌─────────────────────────────────────────────────────────┐
│                    FRONTEND (Flutter)                    │
│  ┌─────────────────────────────────────────────────┐   │
│  │  UI Layer (Dart - 10 files)                     │   │
│  │  - ConsoleLandingPage (main UI shell)           │   │
│  │  - NavigationSidebar (collapsible nav)          │   │
│  │  - ArchitechPage (module UI)                    │   │
│  └─────────────────────────────────────────────────┘   │
│  ┌─────────────────────────────────────────────────┐   │
│  │  API Layer (CQRS Client)                        │   │
│  │  - CqrsApiClient (Result<T> error handling)     │   │
│  │  - Type-safe endpoints from OpenAPI             │   │
│  │  - Serializable commands/queries                │   │
│  └─────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘
                          │ HTTP
                          ↓
┌─────────────────────────────────────────────────────────┐
│              BACKEND (ASP.NET Core 8.0)                 │
│  ┌─────────────────────────────────────────────────┐   │
│  │  API Layer (Controllers + Endpoints)            │   │
│  │  - OpenHarbor auto-generated controllers        │   │
│  │  - Manual endpoint registration                 │   │
│  │  - Global exception handling                    │   │
│  │  - Swagger/OpenAPI documentation                │   │
│  └─────────────────────────────────────────────────┘   │
│                          ↓
│  ┌─────────────────────────────────────────────────┐   │
│  │  CQRS Layer (Business Logic)                    │   │
│  │  - Commands (6): Create, Update, Delete, etc.   │   │
│  │  - Queries (7): Health, Get*, List*             │   │
│  │  - FluentValidation on commands                 │   │
│  └─────────────────────────────────────────────────┘   │
│                          ↓
│  ┌─────────────────────────────────────────────────┐   │
│  │  Data Access Layer (EF Core)                    │   │
│  │  - CodexDbContext                               │   │
│  │  - 5 Entities: Agent, AgentTool, Execution,     │   │
│  │    Conversation, ConversationMessage            │   │
│  │  - AES-256 encryption for API keys              │   │
│  │  - Dynamic query providers                      │   │
│  └─────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘
                          │
                          ↓
              ┌───────────────────────┐
              │  PostgreSQL 15 (Docker) │
              └───────────────────────┘

---

Directory Structure

CODEX_ADK/
├── BACKEND/              (29MB) - C# ASP.NET Core 8.0 API
│   ├── Codex.Api/        - Controllers, endpoints, middleware, Program.cs
│   ├── Codex.CQRS/       - Commands (6) + Queries (7)
│   ├── Codex.Dal/        - EF Core entities, DbContext, migrations, services
│   ├── docs/             - OpenAPI spec, architecture docs, API reference
│   ├── docker-compose.yml
│   ├── CLAUDE.md
│   ├── DEPLOYMENT_STATUS.md
│   └── BACKEND-READINESS.md
│
└── FRONTEND/             (829MB) - Flutter/Dart mobile & web app
    ├── lib/              - Dart source (10 files)
    │   ├── main.dart     - App entry point
    │   ├── theme.dart    - Svrnty brand colors/fonts
    │   ├── console_landing_page.dart - Main UI shell
    │   ├── api/          - CQRS API client layer
    │   │   ├── client.dart
    │   │   ├── types.dart
    │   │   ├── endpoints/
    │   │   └── generated/ - AUTO-GENERATED from OpenAPI
    │   ├── components/   - NavigationSidebar
    │   └── pages/        - ArchitechPage
    ├── pubspec.yaml      - Dependencies
    ├── README_API.md     - API integration guide (14KB)
    ├── CLAUDE.md         - Development guidelines
    ├── .claude-docs/     - Strict typing, response protocol
    └── web/ios/android/macos/linux/windows/

---

Technology Stack

Backend

Component	Technology	Version
Framework	ASP.NET Core	8.0 LTS
Language	C#	.NET 8.0
CQRS	OpenHarbor.CQRS	8.1.0-rc1
ORM	Entity Framework Core	8.0.11
Database	PostgreSQL	15 (Docker)
Validation	FluentValidation	11.3.1
Query Engine	PoweredSoft.DynamicQuery	3.0.1
Documentation	Swagger/OpenAPI	3.0.1

Runs on: http://localhost:5246 (HTTP) or https://localhost:7108 (HTTPS)

Frontend

Component	Technology	Version
Framework	Flutter	3.x
Language	Dart	3.9.2+
UI Library	GetWidget	7.0.0
Icons	Iconsax	0.0.8
Animations	Animate Do	3.1.2
HTTP Client	http	1.2.2
JSON	json_annotation	4.9.0

Fonts: Montserrat (UI), IBM Plex Mono (code) Theme: Dark theme with Svrnty brand colors (Crimson Red #C44D58, Slate Blue #475C6C)

---

API Endpoints (16 Total)

Commands (6 endpoints - Write Operations)

1. POST /api/command/createAgent - Create AI agent
2. POST /api/command/updateAgent - Update agent config
3. POST /api/command/deleteAgent - Soft delete agent
4. POST /api/command/createConversation - Create conversation → returns {id: Guid}
5. POST /api/command/startAgentExecution - Start execution → returns {id: Guid}
6. POST /api/command/completeAgentExecution - Complete execution with results

Queries (4 endpoints - Single Value Reads)

7. POST /api/query/health - Health check → bool
8. POST /api/query/getAgent - Get agent details → AgentDto
9. POST /api/query/getAgentExecution - Get execution → AgentExecutionDto
10. POST /api/query/getConversation - Get conversation → ConversationDto

List Endpoints (6 endpoints - GET Reads)

11. GET /api/agents - List all agents (100 limit)
12. GET /api/conversations - List all conversations (100 limit)
13. GET /api/executions - List all executions (100 limit)
14. GET /api/agents/{id}/conversations - Agent conversations
15. GET /api/agents/{id}/executions - Agent execution history
16. GET /api/executions/status/{status} - Filter by status

Contract: All endpoints documented in /BACKEND/docs/openapi.json

---

Database Schema (5 Entities)

1. Agent

Purpose: Store AI agent configurations with encrypted API keys

Key Fields:

• Id (Guid, PK)
• Name, Description
• AgentType (enum: Assistant, CodeGenerator, Analyzer, Custom)
• Status (enum: Active, Inactive, Archived)
• ModelProviderType (enum: OpenAI, Anthropic, Ollama)
• ModelIdentifier (string - e.g., "gpt-4o", "claude-3-5-sonnet")
• EncryptedApiKey (string - AES-256 encrypted)
• SystemPrompt (text)
• MaxTokens, Temperature
• CreatedAt, UpdatedAt, IsDeleted

Relationships:

• Has many AgentTools
• Has many Conversations
• Has many AgentExecutions

2. AgentTool

Purpose: Define tools/capabilities available to agents

Key Fields:

• Id (Guid, PK)
• AgentId (FK)
• ToolType (enum: WebSearch, CodeExecution, FileAccess, ApiCall, Custom)
• Name, Description
• Configuration (JSON)

3. Conversation

Purpose: Track message exchanges with agents

Key Fields:

• Id (Guid, PK)
• AgentId (FK)
• Title
• CreatedAt, UpdatedAt

Relationships:

• Belongs to Agent
• Has many ConversationMessages

4. ConversationMessage

Purpose: Individual messages in conversations

Key Fields:

• Id (Guid, PK)
• ConversationId (FK)
• Role (enum: User, Assistant, System)
• Content (text)
• TokenCount (int)
• CreatedAt

5. AgentExecution

Purpose: Track agent execution runs with metrics

Key Fields:

• Id (Guid, PK)
• AgentId (FK)
• Status (enum: Pending, Running, Completed, Failed, Cancelled)
• StartedAt, CompletedAt
• InputData, OutputData (JSON)
• TotalTokensUsed, Cost (decimal)
• ErrorMessage

---

Key Design Patterns

1. CQRS (Command Query Responsibility Segregation)

• Commands: Write operations (create, update, delete) - return void or single values
• Queries: Read operations (get, list) - return typed data
• Benefits: Clear separation of concerns, optimized reads vs writes

2. Module System (PoweredSoft.Module)

• AppModule: Orchestrates all sub-modules
  • CommandsModule: Registers all command handlers + validators
  • QueriesModule: Registers all query handlers
  • DalModule: Registers EF Core DbContext + query overrides

3. Repository Pattern (via EF Core)

• CodexDbContext provides data access abstraction
• No raw SQL (all queries through LINQ)
• Migrations managed via EF Core CLI

4. Result Pattern (Frontend)

• No try-catch blocks in API layer
• All errors via Result<T> type (Success or Error)
• Functional error handling

5. Contract-First Development

• OpenAPI schema is single source of truth
• Backend exports schema → Frontend generates types
• Type safety across the entire stack

---

Security Features

Backend

✅ AES-256 Encryption - All API keys encrypted at rest ✅ Rate Limiting - 1000 requests/min per client ✅ CORS Configuration - Controlled origins ✅ Global Exception Handling - No sensitive data leaks ✅ FluentValidation - Input validation on all commands

❌ Missing: JWT authentication (planned for v2) ❌ Missing: HTTPS enforcement in production ❌ Missing: API key rotation

Frontend

✅ Type Safety - Strict typing, no dynamic types ✅ Result Error Handling - No unhandled exceptions ✅ API Contract Validation - Types verified against schema

❌ Missing: Authentication token storage ❌ Missing: Secure credential handling

---

Development Workflow

Backend Setup

cd BACKEND
docker-compose up -d  # Start PostgreSQL + Ollama
dotnet ef database update --project Codex.Dal
dotnet run --project Codex.Api/Codex.Api.csproj

Verify: Open http://localhost:5246/swagger

Frontend Setup

cd FRONTEND
flutter pub get
flutter run -d macos  # or -d chrome, -d ios

Database Migrations

# Add new migration
dotnet ef migrations add MigrationName --project Codex.Dal

# Apply migration
dotnet ef database update --project Codex.Dal

API Contract Export

cd BACKEND
./export-openapi.sh  # Exports to docs/openapi.json
cp docs/openapi.json ../FRONTEND/lib/api-schema.json

Testing

Backend:

cd BACKEND
./test-endpoints.sh  # Manual endpoint testing

Frontend:

cd FRONTEND
flutter analyze
flutter test
./scripts/verify_api_types.sh

---

Important Files to Know

Backend

File	Purpose	Lines
BACKEND/Codex.Api/Program.cs	App startup & configuration	224
BACKEND/Codex.Dal/CodexDbContext.cs	EF Core DbContext	187
BACKEND/docs/openapi.json	API contract (auto-generated)	-
BACKEND/docs/ARCHITECTURE.md	Design decisions	-
BACKEND/BACKEND-READINESS.md	MVP completion assessment	-

Frontend

File	Purpose	Lines
FRONTEND/lib/main.dart	App entry point	24
FRONTEND/lib/console_landing_page.dart	Main UI shell	400+
FRONTEND/lib/api/client.dart	CQRS API client	401
FRONTEND/README_API.md	API integration guide	14KB
FRONTEND/.claude-docs/strict-typing.md	Type safety rules	-

---

Current Status

Backend (Grade: A-)

✅ All 16 endpoints working ✅ Database migrations applied ✅ FluentValidation on all commands ✅ OpenAPI documentation complete ✅ Docker services running (PostgreSQL, Ollama) ✅ AES-256 encryption for API keys ✅ Rate limiting configured ✅ Global exception handling

⚠️ Ready for: Local development, internal testing, frontend integration ❌ Not ready for: Public internet, production with real users

Frontend (Grade: Development Phase)

✅ UI shell implemented (ConsoleLandingPage) ✅ Navigation sidebar working ✅ API client layer built ✅ Type-safe endpoint structure ✅ Dark theme with Svrnty branding

⏳ Pending: Full API integration, module pages, testing

---

Key Principles for Development

Backend (from CLAUDE.md)

1. Pragmatism over Perfection - Ship MVP, iterate later
2. Contract-First - OpenAPI spec drives all changes
3. Type Safety - No dynamic types, strong typing everywhere
4. Validation First - All commands validated before execution
5. Security by Default - Encrypt sensitive data, validate inputs

Frontend (from CLAUDE.md)

1. Strict Typing Only - No dynamic, var, or untyped code
2. Result Error Handling - No try-catch in API layer
3. API Contract Sync - Always verify types against schema
4. Response Protocol - Structured communication format
5. Component Reusability - Build reusable UI components

---

External Integrations

1. OpenAI API - GPT-4o models (API key encrypted)
2. Anthropic API - Claude models (API key encrypted)
3. Ollama - Local LLM inference (Docker container on port 11434)
4. PostgreSQL - Database (Docker container on port 5432)

---

Future Roadmap (v2+)

Planned Features

• JWT authentication & authorization
• Real-time execution updates (SignalR/WebSockets)
• Pagination for large datasets
• API key rotation
• Agent templates & marketplace
• Multi-tenancy support
• Advanced metrics & analytics
• Export/import agent configurations

Known Limitations (MVP v1.0.0)

• No authentication (all endpoints public)
• 100-item limit on list endpoints
• No pagination
• No real-time updates
• Basic error handling (no retry logic)
• Local development only (not production-hardened)

---

Quick Reference

Environment Variables

# Backend
DATABASE_URL=Host=localhost;Database=codex;Username=postgres;Password=postgres
ENCRYPTION_KEY=your-32-character-encryption-key

# Frontend
API_BASE_URL=http://localhost:5246

Default Ports

• Backend API: 5246 (HTTP), 7108 (HTTPS)
• PostgreSQL: 5432
• Ollama: 11434
• Flutter Web: 62000 (dev server)

Key Commands

# Backend
dotnet build
dotnet run --project Codex.Api/Codex.Api.csproj
dotnet ef migrations add <Name> --project Codex.Dal
dotnet ef database update --project Codex.Dal
./export-openapi.sh

# Frontend
flutter pub get
flutter run -d macos
flutter build macos
flutter analyze
flutter test

# Docker
docker-compose up -d
docker-compose down
docker-compose logs -f

---

Documentation Index

Backend Docs

• /BACKEND/README.md - Overview
• /BACKEND/CLAUDE.md - Development guidelines
• /BACKEND/docs/ARCHITECTURE.md - Design decisions
• /BACKEND/docs/COMPLETE-API-REFERENCE.md - Endpoint docs
• /BACKEND/BACKEND-READINESS.md - MVP assessment
• /BACKEND/DEPLOYMENT_STATUS.md - Deployment readiness

Frontend Docs

• /FRONTEND/README.md - Overview
• /FRONTEND/README_API.md - API integration guide (14KB)
• /FRONTEND/CLAUDE.md - Development guidelines
• /FRONTEND/.claude-docs/strict-typing.md - Type safety rules
• /FRONTEND/.claude-docs/response-protocol.md - Response protocol
• /FRONTEND/.claude-docs/api-contract-workflow.md - API workflow

---

Contact & Support

Project Name: CODEX_ADK (Svrnty Console) Version: MVP v1.0.0 Status: Backend Ready, Frontend Integration Pending License: (Not specified) Repository: (Local development - no remote specified)

---

This context document was generated on 2025-10-26 by Claude Code based on comprehensive codebase analysis.