docs/ARCHITECTURE_DIAGRAMS.md

# Architecture Diagram

## System Architecture

```mermaid
graph TB
    subgraph Client["🖥️ Client Layer"]
        WEB["React Frontend<br/>Vite + Dashboard"]
        API_CLIENT["API Client<br/>Axios"]
    end

    subgraph API_LAYER["🌐 API Layer"]
        FASTAPI["FastAPI Application"]
        ROUTES["Routes<br/>Tasks | Workflows | Health"]
        MIDDLEWARE["Middleware<br/>CORS | Auth | Logging"]
    end

    subgraph ORCHESTRATION["🤖 Orchestration Layer"]
        GRAPH["LangGraph Workflow"]
        STATE_MGR["State Manager"]
    end

    subgraph AGENTS["🧠 Agent Layer"]
        MEMORY_AG["Memory Agent<br/>Retrieval"]
        PLANNER_AG["Planner Agent<br/>Decomposition"]
        EXECUTOR_AG["Executor Agent<br/>Execution"]
        CRITIC_AG["Critic Agent<br/>Evaluation"]
    end

    subgraph TOOLS["🔧 Tool Layer"]
        WEB_SEARCH["Web Search<br/>DuckDuckGo"]
        FETCH_URL["URL Fetch<br/>Content Reader"]
        CALCULATOR["Calculator<br/>Math Eval"]
        PYTHON_RUN["Python Executor<br/>Sandbox"]
    end

    subgraph STORAGE["💾 Storage Layer"]
        REDIS["Redis Cache<br/>Hot Memory"]
        SQLITE["SQLite DB<br/>Persistent"]
        POSTGRES["PostgreSQL<br/>Production"]
    end

    subgraph MONITORING["📊 Monitoring"]
        LOGGER["Logger<br/>Structured Logs"]
        METRICS["Metrics<br/>Prometheus"]
        HEALTH["Health Checks<br/>Status"]
    end

    WEB -->|REST API| API_CLIENT
    API_CLIENT -->|HTTP| FASTAPI
    FASTAPI --> MIDDLEWARE
    MIDDLEWARE --> ROUTES
    ROUTES --> ORCHESTRATION
    
    GRAPH -->|Coordinates| MEMORY_AG
    GRAPH -->|Coordinates| PLANNER_AG
    GRAPH -->|Coordinates| EXECUTOR_AG
    GRAPH -->|Coordinates| CRITIC_AG
    
    STATE_MGR -->|Manages| GRAPH
    
    EXECUTOR_AG -->|Uses| WEB_SEARCH
    EXECUTOR_AG -->|Uses| FETCH_URL
    EXECUTOR_AG -->|Uses| CALCULATOR
    EXECUTOR_AG -->|Uses| PYTHON_RUN
    
    MEMORY_AG -->|Read/Write| REDIS
    MEMORY_AG -->|Persistent| SQLITE
    
    CRITIC_AG -->|Store Results| REDIS
    
    ORCHESTRATION -->|Monitor| LOGGER
    ORCHESTRATION -->|Metrics| METRICS
    ROUTES -->|Health| HEALTH
    
    POSTGRES -.->|Production| REDIS
```

## Data Flow Diagram

```mermaid
sequenceDiagram
    User->>Frontend: Submit Task
    Frontend->>API: POST /tasks
    API->>StateManager: Create Initial State
    StateManager->>Memory: Retrieve Context
    Memory->>Redis: Check Hot Cache
    Redis-->>Memory: Return Cached Data
    Memory-->>Orchestration: Context Ready
    Orchestration->>Planner: Plan Task
    Planner-->>StateManager: Update State with Plan
    StateManager->>Executor: Execute Step 1
    Executor->>Tools: Call Tool
    Tools-->>Executor: Tool Result
    Executor-->>StateManager: Step Complete
    StateManager->>Critic: Evaluate Result
    Critic-->>StateManager: Approval/Rejection
    alt Approved
        StateManager->>Memory: Store Learning
        Memory->>SQLite: Persist Memory
    else Rejected
        StateManager->>Planner: Replan
    end
    StateManager->>Frontend: Return Result
    Frontend->>User: Display Results
```

## Workflow State Machine

```mermaid
stateDiagram-v2
    [*] --> PENDING: Task Received
    
    PENDING --> PLANNING: Begin Planning
    PLANNING --> PLANNING: Decompose Task
    PLANNING --> EXECUTING: Plan Ready
    PLANNING --> FAILED: Planning Failed
    
    EXECUTING --> EXECUTING: Execute Step
    EXECUTING --> EXECUTING: Retry on Failure
    EXECUTING --> EVALUATION: All Steps Done
    EXECUTING --> FAILED: Max Retries Exceeded
    
    EVALUATION --> EVALUATION: Critic Evaluates
    EVALUATION --> STORING: Quality Approved
    EVALUATION --> PLANNING: Needs Replanning
    
    STORING --> STORING: Save to Memory
    STORING --> COMPLETED: Success
    
    FAILED --> [*]
    COMPLETED --> [*]
```

## Agent Interaction Diagram

```mermaid
graph LR
    subgraph Input["Input"]
        TASK["📝 Task"]
    end
    
    subgraph Agents["Agent Pipeline"]
        MEM["🧠 Memory<br/>Retrieve Context"]
        PLAN["📋 Planner<br/>Decompose"]
        EXEC["⚙️ Executor<br/>Execute"]
        CRIT["🔍 Critic<br/>Evaluate"]
        STORE["💾 Memory Store<br/>Learn"]
    end
    
    subgraph Output["Output"]
        RESULT["✅ Result"]
    end
    
    TASK --> MEM
    MEM --> PLAN
    PLAN --> EXEC
    EXEC --> CRIT
    CRIT -->|Approved| STORE
    CRIT -->|Rejected| PLAN
    STORE --> RESULT
```

## Technology Stack

```mermaid
graph TB
    subgraph Frontend
        REACT["React 18"]
        VITE["Vite"]
        AXIOS["Axios"]
    end
    
    subgraph Backend
        FASTAPI["FastAPI"]
        LANGGRAPH["LangGraph"]
        PYDANTIC["Pydantic"]
    end
    
    subgraph LLM
        OPENAI["OpenAI API<br/>gpt-4 / gpt-4o-mini"]
    end
    
    subgraph Storage
        REDIS["Redis"]
        SQLITE["SQLite"]
        POSTGRES["PostgreSQL"]
    end
    
    subgraph DevOps
        DOCKER["Docker"]
        COMPOSE["Docker Compose"]
        K8S["Kubernetes"]
    end
    
    REACT --> VITE
    VITE --> AXIOS
    AXIOS -.->|HTTP| FASTAPI
    FASTAPI --> LANGGRAPH
    FASTAPI --> PYDANTIC
    LANGGRAPH -->|Calls| OPENAI
    FASTAPI --> REDIS
    FASTAPI --> SQLITE
    FASTAPI --> POSTGRES
    DOCKER --> COMPOSE
    COMPOSE --> K8S
```

## Deployment Architecture

```mermaid
graph TB
    subgraph Local["Local Development"]
        LOCAL_FRONTEND["Frontend<br/>localhost:3000"]
        LOCAL_BACKEND["Backend<br/>localhost:8000"]
        LOCAL_REDIS["Redis<br/>localhost:6379"]
    end
    
    subgraph Docker["Docker Environment"]
        DOCKER_FRONTEND["Frontend Container"]
        DOCKER_BACKEND["Backend Container"]
        DOCKER_REDIS["Redis Container"]
        DOCKER_POSTGRES["PostgreSQL Container"]
    end
    
    subgraph Production["Production/Cloud"]
        LB["Load Balancer"]
        BACKEND_REPLICAS["Backend Replicas<br/>K8s Pods"]
        REDIS_CLUSTER["Redis Cluster"]
        POSTGRES_MANAGED["Managed PostgreSQL"]
        CDN["CDN<br/>Frontend Static"]
    end
    
    LOCAL_FRONTEND -.->|Dev| LOCAL_BACKEND
    LOCAL_BACKEND -.->|Dev| LOCAL_REDIS
    
    DOCKER_FRONTEND -->|Compose| DOCKER_BACKEND
    DOCKER_BACKEND -->|Compose| DOCKER_REDIS
    DOCKER_BACKEND -->|Compose| DOCKER_POSTGRES
    
    LB --> BACKEND_REPLICAS
    BACKEND_REPLICAS --> REDIS_CLUSTER
    BACKEND_REPLICAS --> POSTGRES_MANAGED
    CDN -.->|Static| BACKEND_REPLICAS
```