# elkar-ai/elkar-a2a architecture

> Architecture diagram of the GitHub repository elkar-ai/elkar-a2a, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/elkar-ai/elkar-a2a
- Repository: https://github.com/elkar-ai/elkar-a2a

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Swimlanes
    subgraph "Client" 
        direction TB
        ReactSPA["React SPA\n(a2a-client)"]:::client
        OpenAPIClient["OpenAPI TS Client\n(a2a-client/generated-api)"]:::client
        FrontendSrc["Pages/Components\n(a2a-client/src)"]:::client
        PythonAPIClient["Python SDK API Client\n(src/elkar/api_client/client.py)"]:::python
    end

    subgraph "Rust Connector Service"
        direction TB
        Router["Router\n(app/connector/src/router.rs)"]:::backend
        Handler["Handler Layer\n(app/connector/src/handler/)"]:::backend
        Service["Service Layer\n(app/connector/src/service/)"]:::backend
        ProtocolCrate["Protocol Crate\n(app/connector/crates/agent2agent/)"]:::backend
        DBCrate["DB Schema Crate\n(app/connector/crates/database_schema/)"]:::backend
        SupabaseCrate["Supabase Integration\n(app/connector/crates/supabase/)"]:::backend
        DieselConfig["Diesel Config\n(app/connector/diesel.toml)"]:::backend
        Migrations["Migrations\n(app/connector/migrations/)"]:::backend
        API_Doc["API Doc Generator\n(app/connector/src/api_doc.rs)"]:::backend
        AsyncTest["Async Test Utils\n(app/connector/src/async_test_utils.rs)"]:::backend
        MainEntrypoint["Main Entrypoint\n(app/connector/src/main.rs)"]:::backend
    end

    subgraph "Persistence & External"
        direction TB
        Postgres["PostgreSQL DB\n(Managed via Diesel)"]:::database
        Supabase["Supabase Auth/Storage"]:::database
        DockerCompose["Docker Compose\n(app/connector/docker-compose.yml)"]:::external
        Makefile["Makefile & Scripts\n(app/connector/Makefile)"]:::external
        CI["CI/CD Workflows\n(.github/workflows/)"]:::external
    end

    subgraph "Python Self-Hosted Path"
        direction TB
        A2AServer["A2A Server\n(src/elkar/host/server.py)"]:::python
        PythonTaskManager["TaskManager\n(src/elkar/task_manager/)"]:::python
        PythonStoreQueue["Store & Queue\n(src/elkar/store/ & src/elkar/task_queue/)"]:::python
        InprocClient["In-process Client & TaskManager Glue\n(src/elkar/client/)"]:::python
        Orchestrator["Orchestrator\n(src/elkar/a2a_orchestrator_mcp.py)"]:::python
    end

    %% Data Flows
    ReactSPA -->|HTTP/REST| Router
    OpenAPIClient -->|HTTP/REST| Router
    FrontendSrc --> OpenAPIClient

    PythonAPIClient -->|HTTP/REST| Router

    Router -->|"calls Handler"| Handler
    Handler -->|"invokes Service"| Service
    Service -->|"queries Diesel ORM"| Postgres
    Service -->|"uses Supabase crate"| Supabase

    DockerCompose --> RustConnector["Rust Connector Service"]
    DockerCompose --> Postgres

    CI --> RustConnector

    %% Python Self-Hosted Flows
    InprocClient -->|in-process| A2AServer
    A2AServer --> PythonTaskManager
    PythonTaskManager --> PythonStoreQueue
    A2AServer --> PythonStoreQueue
    InprocClient -->|manages| Orchestrator

    %% Styles
    classDef client fill:#D0E8FF,stroke:#0366d6
    classDef backend fill:#DFF7DF,stroke:#28A745
    classDef database fill:#FFE5D9,stroke:#F2604C
    classDef external fill:#F0F0F0,stroke:#A0A0A0
    classDef python fill:#FFEDB3,stroke:#D69E00

    %% Click Events
    click ReactSPA "https://github.com/elkar-ai/elkar-a2a/tree/main/a2a-client/"
    click OpenAPIClient "https://github.com/elkar-ai/elkar-a2a/tree/main/a2a-client/generated-api/"
    click FrontendSrc "https://github.com/elkar-ai/elkar-a2a/tree/main/a2a-client/src/"
    click Router "https://github.com/elkar-ai/elkar-a2a/blob/main/app/connector/src/router.rs"
    click Handler "https://github.com/elkar-ai/elkar-a2a/tree/main/app/connector/src/handler/"
    click Service "https://github.com/elkar-ai/elkar-a2a/tree/main/app/connector/src/service/"
    click ProtocolCrate "https://github.com/elkar-ai/elkar-a2a/tree/main/app/connector/crates/agent2agent/src/"
    click DBCrate "https://github.com/elkar-ai/elkar-a2a/tree/main/app/connector/crates/database_schema/src/"
    click SupabaseCrate "https://github.com/elkar-ai/elkar-a2a/tree/main/app/connector/crates/supabase/src/"
    click DieselConfig "https://github.com/elkar-ai/elkar-a2a/blob/main/app/connector/diesel.toml"
    click Migrations "https://github.com/elkar-ai/elkar-a2a/tree/main/app/connector/migrations/"
    click DockerCompose "https://github.com/elkar-ai/elkar-a2a/blob/main/app/connector/docker-compose.yml"
    click Makefile "https://github.com/elkar-ai/elkar-a2a/tree/main/app/connector/Makefile"
    click API_Doc "https://github.com/elkar-ai/elkar-a2a/blob/main/app/connector/src/api_doc.rs"
    click AsyncTest "https://github.com/elkar-ai/elkar-a2a/blob/main/app/connector/src/async_test_utils.rs"
    click MainEntrypoint "https://github.com/elkar-ai/elkar-a2a/blob/main/app/connector/src/main.rs"
    click PythonSDK "https://github.com/elkar-ai/elkar-a2a/tree/main/src/elkar/"
    click PythonAPIClient "https://github.com/elkar-ai/elkar-a2a/blob/main/src/elkar/api_client/client.py"
    click A2AServer "https://github.com/elkar-ai/elkar-a2a/blob/main/src/elkar/host/server.py"
    click PythonTaskManager "https://github.com/elkar-ai/elkar-a2a/tree/main/src/elkar/task_manager/"
    click PythonStoreQueue "https://github.com/elkar-ai/elkar-a2a/tree/main/src/elkar/store/"
    click InprocClient "https://github.com/elkar-ai/elkar-a2a/blob/main/src/elkar/client/a2a_client.py"
    click Orchestrator "https://github.com/elkar-ai/elkar-a2a/blob/main/src/elkar/a2a_orchestrator_mcp.py"
    click CI "https://github.com/elkar-ai/elkar-a2a/tree/main/.github/workflows/"
```
