# agntcy/dir architecture

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

- Interactive diagram: https://gitdiagram.com/agntcy/dir
- Repository: https://github.com/agntcy/dir

## Overview

##### Project type and purpose
- This is a full-stack, Go-based “Agent Directory” system comprising:
- A CLI tool (`cli/`) for end-users
- Multi-language SDKs (`sdk/`, `client/`) for programmatic access
- A monolithic API server (`server/`) exposing gRPC endpoints for storage, routing, search, sign, and sync
- An auxiliary “hub” service (`hub/`) handling authentication, tenant/org management, and session storage
- A P2P network layer for peer discovery and distributed data exchange
- Deployment artifacts (Docker, Helm charts) and end-to-end tests
- Purpose: publish, discover, and exchange AI agent data models over a distributed network, with provable security, versioning, and extensibility.

##### File structure
- Top-level modules:
- `api/` – Protobuf definitions and generated Go code for all services (core, routing, search, sign, store)
- `cli/` – Command-line client with subcommands (publish, search, sync, sign, etc.)
- `client/` – Go SDK for embedding client logic in other Go apps
- `sdk/` – Python and JavaScript SDKs
- `server/` – API server: controllers → services → datastore/database modules → P2P routing
- `hub/` – Separate service for authentication, tenant/org management, session persistence
- `install/` – Helm charts and Docker Compose files for deployment
- `e2e/` – End-to-end test harness
- Internal server layers (in `server/`):
- `config/` – application configuration
- `controller/` – translates gRPC calls into service invocations
- `datastore/` – generic store interface
- `database/` – metadata storage (SQLite)
- `store/` – object persistence (local fs, OCI registries, cache)
- `routing/` – P2P discovery using libp2p
- `sync/` – background sync scheduler and workers
- `types/` – port and adapter definitions (hexagonal architecture)

##### README for additional insights
- The README calls out: Data Models, Dev Kit (CLI), Plugins, Announce, Discover, Security layers.
- Deployment via Taskfile, Docker Compose, or Helm chart, exposing at least two containers: `dir-apiserver` and `dir-ctl` (CLI), plus `hub` service.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User-facing Clients
    subgraph "User-facing Clients"
        direction TB
        CLI["dir-ctl CLI"]:::client
        GoSDK["Go SDK"]:::client
        PySDK["Python SDK"]:::client
        JSSDK["JavaScript SDK"]:::client
    end

    %% Back-end Services
    subgraph "Back-end Services"
        direction TB
        APIServer["dir-apiserver (gRPC API Server)"]:::backend
        subgraph "API Server Modules"
            direction TB
            Config["Configuration Layer"]:::backend
            Controllers["Controllers"]:::backend
            DatastorePort["Datastore Interface (ports)"]:::backend
            Types["Types & Adapters"]:::backend
            subgraph "Service Layer"
                direction TB
                RoutingSvc["Routing Service"]:::backend
                SearchSvc["Search Service"]:::backend
                StoreSvc["Store Service"]:::backend
                SignSvc["Sign Service"]:::backend
                SyncSvc["Sync Scheduler & Workers"]:::backend
            end
            subgraph "Adapters"
                direction TB
                DB["SQLite Metadata DB"]:::persistence
                LocalFS["LocalFS Adapter"]:::persistence
                OCIStore["OCI Registry Adapter"]:::persistence
                CacheAdapter["Cache Adapter"]:::persistence
                P2PRouting["P2P Routing Layer"]:::network
            end
        end

        HubService["Hub Service"]:::backend
        subgraph "Hub Modules"
            direction TB
            HubAPI["Hub API Definitions"]:::backend
            AuthMod["Authentication Module"]:::backend
            SessionStore["Session Store Adapters"]:::backend
            HubCLI["Hub CLI Commands"]:::backend
        end
    end

    %% External Systems
    P2PMesh["P2P Mesh Network"]:::network
    IDP["Identity Provider(s)"]:::external
    OCIRegistry["OCI Registry"]:::external

    %% Deployment & Utilities
    subgraph "Deployment & Tools"
        direction TB
        HelmCharts["Helm Charts"]:::deploy
        DockerCompose["Docker Compose"]:::deploy
        E2ETests["End-to-End Tests"]:::deploy
        ProtobufDefs["Protobuf Definitions & Generated Code"]:::util
        Utils["Utilities & Shared Helpers"]:::util
    end

    %% Connections
    CLI -->|"gRPC" | APIServer
    GoSDK -->|"gRPC"| APIServer
    PySDK -->|"gRPC"| APIServer
    JSSDK -->|"gRPC"| APIServer

    CLI -->|"login API"| HubService

    APIServer -->|"uses"| Config
    APIServer --> Controllers
    Controllers --> Types
    Controllers --> RoutingSvc
    Controllers --> SearchSvc
    Controllers --> StoreSvc
    Controllers --> SignSvc
    Controllers --> SyncSvc

    StoreSvc --> LocalFS
    StoreSvc --> OCIStore
    StoreSvc --> CacheAdapter

    DatastorePort --> DB
    DatastorePort --> LocalFS
    DatastorePort --> OCIStore

    RoutingSvc --> P2PRouting
    P2PRouting --> P2PMesh

    SyncSvc -->|pull/push| OCIRegistry

    HubService --> AuthMod
    HubService --> SessionStore
    AuthMod --> IDP

    %% Deployment connections
    APIServer -->|"packaged in"| HelmCharts
    HubService -->|"packaged in"| HelmCharts
    HelmCharts --> Kubernetes["Kubernetes"]:::external
    DockerCompose -.-> APIServer
    DockerCompose -.-> HubService
    E2ETests --> APIServer
    E2ETests --> HubService

    ProtobufDefs --> APIServer
    ProtobufDefs --> HubService
    Utils --> APIServer
    Utils --> HubService

    %% Click Events
    click CLI "https://github.com/agntcy/dir/tree/main/cli/"
    click GoSDK "https://github.com/agntcy/dir/tree/main/client/"
    click PySDK "https://github.com/agntcy/dir/tree/main/sdk/python/"
    click JSSDK "https://github.com/agntcy/dir/tree/main/sdk/javascript/"
    click APIServer "https://github.com/agntcy/dir/tree/main/server/"
    click Config "https://github.com/agntcy/dir/tree/main/server/config/"
    click Controllers "https://github.com/agntcy/dir/tree/main/server/controller/"
    click DatastorePort "https://github.com/agntcy/dir/tree/main/server/datastore/"
    click DB "https://github.com/agntcy/dir/tree/main/server/database/sqlite/"
    click LocalFS "https://github.com/agntcy/dir/tree/main/server/store/localfs/"
    click OCIStore "https://github.com/agntcy/dir/tree/main/server/store/oci/"
    click CacheAdapter "https://github.com/agntcy/dir/tree/main/server/store/cache/"
    click P2PRouting "https://github.com/agntcy/dir/tree/main/server/routing/"
    click SyncSvc "https://github.com/agntcy/dir/tree/main/server/sync/"
    click Types "https://github.com/agntcy/dir/tree/main/server/types/"
    click HubService "https://github.com/agntcy/dir/tree/main/hub/"
    click HubAPI "https://github.com/agntcy/dir/tree/main/hub/api/"
    click AuthMod "https://github.com/agntcy/dir/tree/main/hub/auth/"
    click SessionStore "https://github.com/agntcy/dir/tree/main/hub/sessionstore/"
    click HubCLI "https://github.com/agntcy/dir/tree/main/hub/cmd/"
    click HelmCharts "https://github.com/agntcy/dir/tree/main/install/charts/"
    click DockerCompose "https://github.com/agntcy/dir/blob/main/install/docker/docker-compose.yml"
    click E2ETests "https://github.com/agntcy/dir/tree/main/e2e/"
    click ProtobufDefs "https://github.com/agntcy/dir/tree/main/api/"
    click Utils "https://github.com/agntcy/dir/tree/main/utils/"

    %% Styles
    classDef client fill:#daf5d7,stroke:#2e7d32,stroke-width:1px
    classDef backend fill:#d0e1f9,stroke:#1e3a8a,stroke-width:1px
    classDef persistence fill:#fde4b9,stroke:#b45309,stroke-width:1px
    classDef network fill:#e5d0f9,stroke:#6d28d9,stroke-width:1px
    classDef external fill:#f0f0f0,stroke:#4b5563,stroke-width:1px
    classDef deploy fill:#d1fae5,stroke:#065f46,stroke-width:1px
    classDef util fill:#f3f4f6,stroke:#374151,stroke-width:1px
```
