Vapora/docs/architecture/README.md

VAPORA Architecture

Comprehensive documentation of VAPORA's system architecture, design patterns, and implementation details.

Architecture Layers

1. Protocol Layer

A2A (Agent-to-Agent) Protocol

• Standard protocol for agent-to-agent communication
• JSON-RPC 2.0 specification compliance
• Agent discovery via Agent Card
• Task dispatch and lifecycle tracking
• See: ADR-0001: A2A Protocol Implementation

MCP (Model Context Protocol)

• Real MCP transport with Stdio and SSE support
• 6 integrated tools for task/agent management
• Backend client integration
• Tool registry with JSON Schema validation

2. Server Layer

vapora-a2a (A2A Server)

• Axum-based HTTP server
• Endpoints: agent discovery, task dispatch, status query, health, metrics
• JSON-RPC 2.0 request/response handling
• SurrealDB persistent storage (production-ready)
• NATS async coordination for task lifecycle events
• Prometheus metrics (/metrics endpoint)
• Integration: AgentCoordinator, TaskManager, CoordinatorBridge
• Tasks survive server restarts (persistent)
• Background NATS listeners for TaskCompleted/TaskFailed

vapora-a2a-client (A2A Client)

• HTTP client library for A2A protocol
• Methods for discovery, dispatch, query
• Exponential backoff retry with jitter (100ms → 5s)
• Smart retry logic (5xx/network YES, 4xx NO)
• Timeout and error handling
• Full serialization support

3. Infrastructure Layer

Kubernetes Deployment

• StatefulSet-based deployment via Kustomize
• Environment-specific overlays (dev, prod)
• RBAC, resource quotas, anti-affinity
• ConfigMap-based A2A integration
• See: ADR-0002: Kubernetes Deployment Strategy

4. Integration Layer

AgentCoordinator Integration

• CoordinatorBridge maps A2A tasks to internal agents
• Task state management
• Background completion tracking

Backend Integration

• SurrealDB for persistent storage
• Multi-tenant scope isolation
• REST API endpoints

Key Components

A2A Protocol Types

Type	Purpose	Location
A2aTask	Task request	protocol.rs
A2aMessage	Message with text/file parts	protocol.rs
A2aTaskStatus	Task state and result	protocol.rs
A2aTaskResult	Execution result with artifacts	protocol.rs
AgentCard	Agent capability advertisement	agent_card.rs

Error Handling

Two-layer strategy:

• Domain Layer: Type-safe Rust errors via thiserror
• Protocol Layer: JSON-RPC 2.0 error format
• See: ADR-0003: Error Handling and JSON-RPC 2.0 Compliance

Crate Dependencies

vapora-a2a (A2A Server)
├── vapora-agents
├── vapora-shared
├── axum
├── tokio
└── serde/serde_json

vapora-a2a-client (A2A Client)
├── vapora-a2a
├── vapora-shared
├── reqwest
├── tokio
└── serde/serde_json

vapora-mcp-server (MCP Transport)
├── vapora-agents
├── vapora-shared
├── axum
├── reqwest
└── serde/serde_json

LLM Routing & Cost Management

NEW: Two comprehensive guides for working with LLM providers (Claude, OpenAI, Gemini, Ollama)

For Developers

• LLM Provider Patterns — Four implementation approaches:

  1. Mocks — Zero-cost development without API subscriptions
  2. SDK Direct — Full integration with official APIs
  3. Add Provider — Extending VAPORA with custom providers
  4. End-to-End — Complete request-to-response flow

• LLM Provider Implementation Guide — How VAPORA implements it today:

  • LLMClient trait abstraction (Claude, OpenAI, Gemini, Ollama)
  • Hybrid routing engine (rules + dynamic + manual override)
  • Cost tracking & token accounting
  • Three-tier budget enforcement
  • Automatic fallback chains
  • Production code examples

Key Insights

Scenario	Pattern	Cost
Local development	Mocks	$0
CI/integration tests	SDK + mocks	$0
Staging/production	SDK real	$varies
Privacy-critical	Ollama local	$0
Cost-optimized	Gemini + Ollama fallback	$0.005/1k

Start here: llm-provider-patterns.md for patterns without subscriptions.

---

Related Documentation

• ADR Index - Architecture decision records
• multi-ia-router.md - Detailed LLM router specification
• Related ADRs:
  • ADR-0007: Multi-Provider LLM Support
  • ADR-0012: Three-Tier LLM Routing
  • ADR-0015: Budget Enforcement
  • ADR-0016: Cost Efficiency Ranking