# a2a-community/a2a-ui architecture

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

- Interactive diagram: https://gitdiagram.com/a2a-community/a2a-ui
- Repository: https://github.com/a2a-community/a2a-ui

## Overview

##### Project Type and Purpose
- This is a full-stack web UI (Next.js/React) tailored for the A2A (Agent-to-Agent) platform.
- It provides real-time chat, agent management, and tracing visualizations, and integrates with external A2A agent servers and Phoenix tracing services.

##### Directory Structure Analysis
- Top level: configuration files (.dockerignore, Dockerfile, docker-compose.yaml, tsconfig.json, etc.), Next.js config (next.config.ts), package manifests.
- src/a2a: domain-specific logic for communicating with the A2A backend—client.ts, schema.ts, and a multi-scoped state folder (agent, host, app, settings).
- src/app: Next.js App Router routes and API endpoints (health check).
- src/components: broken out by feature (chat, layout, common, ui) illustrating a component-based UI.
- src/contexts + src/hooks: state management and custom hooks that glues together React Context and localStorage.
- src/lib: shared utilities (env, logger, error-handler).
- src/types: TypeScript definitions.

##### README Insights
- Tech stack: Next.js 15.3.3, TypeScript, Tailwind CSS + shadcn/ui.
- Features: agent CRUD, real-time status, streaming chat, Phoenix/Jae­ger-style tracing.
- Deployment: Vercel, Docker, Docker Compose.
- Environment configuration and CORS setup for the A2A backend.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        Browser["Browser (User Interface)"]:::ui
        NextServer["Next.js Server"]:::server
        Browser -->|"renders pages / SSR/CSR"| NextServer

        subgraph "Next.js Router & APIs"
            direction TB
            AppRouter["App Router Pages"]:::code
            APIRoutes["API Routes (health)"]:::code
        end
        NextServer -->|"serves"| AppRouter
        NextServer -->|"handles"| APIRoutes

        subgraph "A2A Client & State"
            direction TB
            A2AClient["A2A API Client Module"]:::service
            subgraph "State Management"
                direction TB
                AgentState["AgentState"]:::state
                HostState["HostState"]:::state
                AppState["AppState"]:::state
                SettingsState["SettingsState"]:::state
                StateRegistry["Context Registry"]:::state
            end
            subgraph "Custom Hooks & Persistence"
                direction TB
                useAppState["useAppState"]:::state
                useChat["useChat"]:::state
                useLocalStorage["useLocalStorage"]:::state
                useTrace["useTrace"]:::state
                HooksIndex["hooks/index"]:::state
            end
            subgraph "Shared Utilities"
                direction TB
                Env["env.ts"]:::util
                Logger["logger.ts"]:::util
                ErrorHandler["error-handler.ts"]:::util
                Utils["utils.ts"]:::util
            end
        end

        AppRouter -->|"uses components & hooks"| A2AClient
        AgentState -->|registered in| StateRegistry
        HostState -->|registered in| StateRegistry
        AppState -->|registered in| StateRegistry
        SettingsState -->|registered in| StateRegistry
        StateRegistry -->|"provides context"| Browser
        Browser -->|updates state| AgentState
        Browser -->|updates state| HostState
        Browser -->|updates state| AppState
        Browser -->|updates state| SettingsState
        useLocalStorage -.->|persists| StateRegistry
        useAppState -->|wraps context| StateRegistry
        useChat -->|uses A2AClient| A2AClient
        useTrace -->|fetches| Phoenix
        A2AClient -->|HTTP/WebSocket calls| A2AServer
        A2AClient -->|"fetch schema"| Schema["schema.ts"]:::service
        ErrorHandler -->|handles errors for| A2AClient
        Logger -->|logs events for| A2AClient

    end

    %% External Services
    subgraph "External Services"
        direction TB
        A2AServer["A2A Agent Server"]:::externalService
        Phoenix["Phoenix Tracing Service"]:::externalService
    end

    A2AServer -->|stores tasks in DB| DB["Agent DB"]:::data
    Phoenix -->|provides tracing data| Browser

    %% Click Events
    click AppRouter "https://github.com/a2a-community/a2a-ui/blob/main/src/app/layout.tsx"
    click AppRouter "https://github.com/a2a-community/a2a-ui/blob/main/src/app/page.tsx"
    click AppRouter "https://github.com/a2a-community/a2a-ui/tree/main/src/app/pages/"
    click APIRoutes "https://github.com/a2a-community/a2a-ui/blob/main/src/app/api/health/route.ts"
    click A2AClient "https://github.com/a2a-community/a2a-ui/blob/main/src/a2a/client.ts"
    click Schema "https://github.com/a2a-community/a2a-ui/blob/main/src/a2a/schema.ts"
    click AgentState "https://github.com/a2a-community/a2a-ui/blob/main/src/a2a/state/agent/AgentState.ts"
    click HostState "https://github.com/a2a-community/a2a-ui/blob/main/src/a2a/state/host/HostState.ts"
    click AppState "https://github.com/a2a-community/a2a-ui/blob/main/src/a2a/state/app/AppState.ts"
    click SettingsState "https://github.com/a2a-community/a2a-ui/blob/main/src/a2a/state/settings/SettingsState.ts"
    click StateRegistry "https://github.com/a2a-community/a2a-ui/blob/main/src/contexts/index.tsx"
    click useAppState "https://github.com/a2a-community/a2a-ui/blob/main/src/hooks/useAppState.ts"
    click useChat "https://github.com/a2a-community/a2a-ui/blob/main/src/hooks/useChat.ts"
    click useLocalStorage "https://github.com/a2a-community/a2a-ui/blob/main/src/hooks/useLocalStorage.ts"
    click useTrace "https://github.com/a2a-community/a2a-ui/blob/main/src/hooks/useTrace.ts"
    click HooksIndex "https://github.com/a2a-community/a2a-ui/blob/main/src/hooks/index.ts"
    click Env "https://github.com/a2a-community/a2a-ui/blob/main/src/lib/env.ts"
    click Logger "https://github.com/a2a-community/a2a-ui/blob/main/src/lib/logger.ts"
    click ErrorHandler "https://github.com/a2a-community/a2a-ui/blob/main/src/lib/error-handler.ts"
    click Utils "https://github.com/a2a-community/a2a-ui/blob/main/src/lib/utils.ts"
    click Db "https://github.com/a2a-community/a2a-ui/tree/main/src/components/chat/"
    click LayoutComponents "https://github.com/a2a-community/a2a-ui/tree/main/src/components/layout/"
    click ErrorBoundary "https://github.com/a2a-community/a2a-ui/blob/main/src/components/common/ErrorBoundary.tsx"
    click UIPrimitives "https://github.com/a2a-community/a2a-ui/tree/main/src/components/ui/"
    click TypesIndex "https://github.com/a2a-community/a2a-ui/blob/main/src/types/index.ts"
    click TypesChat "https://github.com/a2a-community/a2a-ui/blob/main/src/types/chat.ts"

    %% Styles
    classDef ui fill:#f9f,stroke:#333,stroke-width:1px
    classDef server fill:#bbf,stroke:#333,stroke-width:1px
    classDef code fill:#ddf,stroke:#333,stroke-width:1px
    classDef service fill:#bfb,stroke:#333,stroke-width:1px
    classDef state fill:#ffb,stroke:#333,stroke-width:1px
    classDef util fill:#fbf,stroke:#333,stroke-width:1px
    classDef externalService fill:#fbb,stroke:#333,stroke-width:1px
    classDef data fill:#afa,stroke:#333,stroke-width:1px
```
