How elkar-ai/elkar-a2a works
Project type and purpose
• Elkar is an open-source, multi-component system for managing AI-agent tasks via the Agent2Agent (A2A) protocol.
• It consists of:
• A web-based front-end (“a2a-client”) (React + TypeScript + Vite) for UI/UX.
• A self-hosted Rust-based backend service (“app/connector”) providing the A2A REST API and persistence (PostgreSQL via Diesel).
• A Python SDK (“src/elkar”) that lets you build agent applications, host A2A servers, and choose between in-memory or managed service stores.
File structure & README insights
• Top-level directories:
• a2a-client: React SPA, OpenAPI-generated API client, pages/components, contexts, hooks.
• app/connector: Rust microservice with crates for protocol, schema, Supabase integration; migrations; Docker; API handlers & services for agents, tasks, tenants, users, events.
• src/elkar: Python package implementing A2A server, task manager, task queue/store, API client, host agent, orchestrator.
• examples, images, CI configs, docs.
• Architectural patterns:
• Frontend-Backend separation (REST).
• Backend as microservice with layered structure: router → handler → service → database.
• SDK library + embedded server (self-host) supporting DI of store/queue.
Main components
A. Clients & UI
• Web Browser → React SPA (“a2a-client”): uses OpenAPI TypeScript client to call backend.
• Python Applications → Python SDK (“src/elkar/api_client”) calls A2A API or instantiates local A2A Server.
B. API Gateway & Backend
• Rust Connector Service (“app/connector”):
• Router (axum or warp)
• Handler layer per resource (agent, task, tenant, user, api_key)
• Service layer performing business logic
• Database layer (Diesel + migrations)
• Protocol crate (agent2agent) for message/event types
• Supabase/PostgreSQL integration crate
C. Persistence & External Services
• PostgreSQL DB (with Diesel)
• Supabase (managed Postgres + Auth)
• Push Notifications / Webhooks (optional external integrations)
D. Python Self-Host Path (alternate)
• A2AServer (ASGI)
• TaskManager, TaskQueue, TaskStore (in-memory or pluggable connectors)
E. Infrastructure & Deployment
• Docker Compose (for Rust service + Postgres + pgvector)
• GitHub Actions (CI/CD)
• Vercel/Netlify or static hosting for frontend
Relationships & data flow
• Browser SPA ←→ Rust Connector (HTTPS/REST)
• Python SDK (API Client) ←→ Rust Connector (HTTPS/REST)
• Rust Connector → PostgreSQL (Diesel ORM)
• Rust Connector → Supabase Auth & Storage (via supabase crate)
• Python A2AServer (self-host) ←→ Python SDK tasks (in-process calls)
• Docker Compose binds Connector ↔ Postgres
Architectural patterns & design principles
• Layered architecture in Rust service:
Router → Handler → Service → DB
• OpenAPI-driven client generation for TypeScript (a2a-client)
• Pluggable Store/Queue abstraction in Python SDK (Strategy pattern)
• Clear domain boundary: Agents, Tasks, Tenants, Users, API Keys