dev-agent/ARCHITECTURE.md

# Universal Dev Agent Architecture

This document describes the high-level architecture of the **Universal Dev Agent**, which acts as a platform-agnostic builder converting natural-language requirements into structured, validated agent specifications.

```mermaid
graph TD
    User([User Prompt / Message]) --> API[FastAPI Layer]
    User --> CLI[CLI Loop]
    API --> SessionService[Conversation & Session Service]
    CLI --> SessionService
    SessionService --> DB[(SQLite Database)]
    SessionService --> DevAgent[LangGraph DevAgent]
    DevAgent --> AnalyzeNode[Analyze Node]
    AnalyzeNode --> LLMService[LLM Service / LiteLLM]
    AnalyzeNode --> RouteAnalysis{Missing Info?}
    RouteAnalysis -- Yes --> ClarifyNode[Clarify Node]
    RouteAnalysis -- No --> GenerateNode[Generate Spec Node]
    ClarifyNode --> END([Awaiting User Input])
    GenerateNode --> ValidateNode[Validate Spec Node]
    ValidateNode --> ValidationService[Validation Service]
    ValidationService --> SchemaValidator[Schema Validator]
    ValidationService --> ConnectionValidator[Connection Validator]
    ValidationService --> ConflictValidator[Conflict Validator]
    ValidationService --> ToolValidator[Tool Validator]
    ValidationService --> WorkflowValidator[Workflow Validator]
    ValidateNode --> RouteValidation{Valid Spec?}
    RouteValidation -- Yes --> FinalizeNode[Finalize Node]
    RouteValidation -- No --> ClarifyNode
    FinalizeNode --> END
```

---

## Core Components

### 1. LangGraph State Machine (`app/agents/`)
The conversational flow is modeled as a state machine using **LangGraph**. The workflow progresses through the following states:
* **`analyze`**: Inspects user messages in the context of the history to extract core fields (triggers, connections, modes, tools).
* **`clarify`**: Formulates questions if critical information is missing or validation errors occur, then pauses execution by returning `END`.
* **`generate`**: Generates a draft JSON Agent Spec according to the Pydantic schemas.
* **`validate`**: Runs the spec through the multi-layer Validation Service.
* **`finalize`**: Marks the spec as validated, increments versions, and prepares the version record.

### 2. Validation Service (`app/validators/`)
A multi-layered validation pipeline guarantees correct, conflict-free, and secure Agent Specs:
1. **Schema Validation**: Uses Pydantic to ensure all fields match required types, structures, and schemas.
2. **Connection Validation**: Verifies connection configurations by type (e.g. `base_url` for REST APIs) and scans the specs to prevent raw credentials (secrets, API keys) from leaking.
3. **Conflict Validation**: Flags conflicting properties, such as a trigger type set to `manual` but containing `cron` configurations.
4. **Tool Validation**: Ensures steps executing `tool_call` actions reference existing tools defined in the spec.
5. **Workflow Validation**: Automatically performs cycle detection to prevent circular execution dependencies, checks that all step dependencies exist, and verifies that step inputs only reference outputs of preceding dependent steps.

### 3. LiteLLM Service (`app/services/llm_service.py`)
Abstracts model provider configuration. Uses `completion()` to execute NLP analysis, clarification question generation, and spec generation.
* **Smart Fallback**: If no LLM API key is configured, a rule-based parser kicks in, ensuring complete conversational flow, spec drafting, and validation run offline.

### 4. Database Layer (`app/db/`)
Uses SQLAlchemy for ORM and SQLite by default.
* **`dev_sessions`**: Persists conversation builder variables like `extracted_requirements`, `draft_spec`, `validation_result`, and current state.
* **`conversation_messages`**: Maintains chronological messages.
* **`agent_specs`** & **`agent_versions`**: Persists generated specifications and auto-increments version tags.