Data Flow

Request Lifecycle

1. Client Request

┌─────────┐     HTTP/HTTPS      ┌─────────────┐
│ Client  │ ──────────────────> │ API Gateway │
│         │  Authorization:     │             │
│         │  Bearer <token>     │             │
└─────────┘                     └─────────────┘

Validation:

• API key authentication
• Rate limit check (Redis-backed)
• Request schema validation
• Content-Security-Policy headers

2. Prompt Processing

┌─────────────┐     ┌─────────────────┐     ┌──────────────┐
│ API Gateway │ --> │ Prompt Manager  │ --> │  LLM Adapter │
│             │     │                 │     │              │
│             │     │ • Load template │     │              │
│             │     │ • Substitute    │     │              │
│             │     │ • Add context   │     │              │
└─────────────┘     └─────────────────┘     └──────────────┘

Operations:

• Load conversation context from store
• Apply system prompts and templates
• Token count estimation
• Cost tracking

3. LLM Invocation

┌──────────────┐     HTTPS/HTTP2     ┌─────────────────┐
│  LLM Adapter │ ──────────────────> │ LLM Provider    │
│              │  Streaming Response │ (OpenAI/Claude/  │
│              │ <────────────────── │  Local Model)   │
└──────────────┘                     └─────────────────┘

Handling:

• Retry logic with exponential backoff
• Circuit breaker for provider failures
• Streaming response handling
• Timeout enforcement

4. Response Parsing

┌─────────────────┐     ┌─────────────────┐
│ LLM Provider    │ --> │ Response Parser │
│                 │     │                 │
│ JSON/Stream     │     │ • Extract text  │
│ with tool calls │     │ • Parse tools   │
│                 │     │ • Validate      │
└─────────────────┘     └─────────────────┘

Validation:

• JSON schema validation for tool calls
• Type checking for arguments
• Permission checking against tool registry

5. Tool Execution (if applicable)

┌─────────────────┐     ┌─────────────────┐     ┌─────────────┐
│ Response Parser │ --> │ Tool Registry   │ --> │   Sandbox   │
│                 │     │                 │     │             │
│ Tool calls      │     │ • Validate      │     │ • gVisor    │
│ detected        │     │ • Authorize     │     │ • Wasmtime  │
│                 │     │ • Route         │     │ • Firecracker│
└─────────────────┘     └─────────────────┘     └─────────────┘

Security checks:

• Tool existence and enabled status
• User permissions for tool
• Resource quota availability
• Input sanitization

6. Sandbox Execution

┌─────────────┐     ┌─────────────────┐     ┌─────────────┐
│   Sandbox   │ --> │ Code/Tool Exec  │ --> │  Result     │
│             │     │                 │     │             │
│ Isolated    │     │ • Run command   │     │ Output      │
│ environment │     │ • Capture I/O   │     │ Exit code   │
│             │     │ • Enforce limits│     │             │
└─────────────┘     └─────────────────┘     └─────────────┘

Constraints:

• CPU time limit (configurable, default 30s)
• Memory limit (configurable, default 256MB)
• Network egress filtering
• Filesystem restrictions

7. Result Aggregation

┌─────────────┐     ┌─────────────────┐     ┌──────────────┐
│   Result    │ --> │ Conversation    │ --> │  LLM Adapter │
│             │     │ Manager         │     │  (if needed) │
│ Tool output │     │                 │     │              │
│             │     │ • Update state  │     │              │
│             │     │ • Check if more │     │              │
│             │     │   tool calls    │     │              │
└─────────────┘     └─────────────────┘     └──────────────┘

Loop detection:

• Maximum tool call iterations (default 10)
• Cycle detection in tool dependencies
• Total execution time limits

8. Response Delivery

┌──────────────┐     ┌─────────────────┐     ┌─────────┐
│ Conversation │ --> │ Response Builder│ --> │ Client  │
│ Manager      │     │                 │     │         │
│              │     │ • Format output │     │         │
│              │     │ • Add metadata  │     │         │
│              │     │ • Set headers   │     │         │
└──────────────┘     └─────────────────┘     └─────────┘

Metadata included:

• Request ID
• Tokens used (input/output)
• Execution time
• Tool calls made
• Cost estimate

9. Async Processing

┌──────────────────────────────────────────────────────────┐
│                    Async Pipeline                        │
├──────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐  │
│  │ Audit Log   │  │ Metrics     │  │ Cost Tracking   │  │
│  │ Writer      │  │ Collector   │  │ & Billing       │  │
│  └─────────────┘  └─────────────┘  └─────────────────┘  │
└──────────────────────────────────────────────────────────┘

Non-blocking operations:

• Structured audit logging
• Prometheus metrics
• Usage tracking
• Alert evaluation

Data Stores

PostgreSQL (Primary Store)

• Conversations and messages
• User accounts and API keys
• Tool definitions and configurations

Redis (Cache/Queue)

• Rate limiting counters
• Session state (short-term)
• Async job queue
• Pub/sub for real-time features

Object Storage (S3/MinIO)

• Large attachments
• Export files
• Audit log archives

State Diagram

                    ┌─────────────┐
         ┌─────────>│   Pending   │
         │          │  (queued)   │
         │          └──────┬──────┘
         │                 │
         │                 v
         │          ┌─────────────┐
         │          │  Processing │
         │          │   (active)  │
         │          └──────┬──────┘
         │                 │
    ┌────┴────┐      ┌─────┴─────┐
    │ Timeout │      │ Complete  │
    │  Error  │      │  Success  │
    └────┬────┘      └─────┬─────┘
         │                 │
         │                 v
         │          ┌─────────────┐
         └─────────>│   Closed    │
                    │  (final)    │
                    └─────────────┘