# codespin-ai/shaman architecture

> Architecture diagram of the GitHub repository codespin-ai/shaman, 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/codespin-ai/shaman
- Repository: https://github.com/codespin-ai/shaman

## Overview

##### Project Type and Purpose
- Shaman is a TypeScript monorepo providing a backend framework to discover, execute, and orchestrate AI agents in a federated, multi-tenant environment.
- It follows a “dual-server” architecture (GraphQL management API vs. A2A execution server) plus a background worker for workflows.

##### High-Level Architecture Components
a. Servers
- GraphQL Management API (node/packages/shaman-gql-server)
- A2A Execution Server (node/packages/shaman-a2a-server)
- Workflow Worker (node/packages/shaman-worker)
b. Infrastructure
- PostgreSQL (with Row-Level Security via shaman-db)
- Redis + BullMQ (job queue for orchestration)
- Observability (metrics, tracing via shaman-observability)
- Security (JWT, API-key, RBAC via shaman-security)
- Logging (centralized via shaman-logger)
c. Core Runtime Packages
- Agent Discovery & Resolution (shaman-git-resolver, shaman-agents)
- Agent Execution Engine (shaman-agent-executor)
- A2A Protocol (shaman-jsonrpc, shaman-a2a-transport, shaman-a2a-client/server)
- LLM Integration (shaman-llm-core + vercel adapter)
- Tool Routing (shaman-tool-router)
- Shared Types & Config (shaman-types, shaman-config)
- Database Management (shaman-db)
d. External Services
- Active: Foreman workflow service
- Planned: Permiso RBAC, Ory Kratos identity

##### Relationships & Data Flows
- **GraphQL Server**
- Reads/Writes PostgreSQL (via shaman-db) for agent metadata, user/tenant data.
- Publishes workflow jobs to Redis/BullMQ.
- Enforces auth/policies via shaman-security.
- Emits observability data via shaman-observability.
- **Workflow Worker**
- Subscribes to Redis job queue.
- For each job:
– Use shaman-git-resolver to fetch agent code.
– Invoke shaman-agent-executor to run the agent logic.
– Agent-executor calls into LLM providers (shaman-llm-core) and tool-router.
– Write execution results back to PostgreSQL.
– Emits metrics/traces/logs.
- **A2A Execution Server**
- Exposes JSON-RPC, REST, SSE endpoints (via shaman-a2a-transport).
- Routes incoming agent-to-agent calls into shaman-agent-executor.
- Publishes events or stores state in DB/Redis if needed.
- **External Foreman**
- (Optional) receives orchestration calls from GraphQL or Worker via @codespin/foreman-client.

##### Architectural Patterns & Principles
- **Dual-Server Separation**: clear boundary between management plane (GraphQL) and execution plane (A2A + Worker).
- **Plugin/Provider Pattern**: LLM providers, transports, and tools are swappable modules.
- **Repository Pattern**: DB access abstracted with named queries and migrations (knex/shaman).
- **Event-Driven Workflow**: BullMQ job queue decouples job producer (GraphQL / A2A) from consumer (Worker).
- **Monorepo with Custom Build**: packages in /node/packages arranged by dependency order; unified versioning.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Servers Layer
    subgraph "Servers"
        direction TB
        GraphQL["GraphQL API<br>(shaman-gql-server)"]:::server
        A2A["A2A Execution Server<br>(shaman-a2a-server)"]:::server
        Worker["Workflow Worker<br>(shaman-worker)"]:::server
    end

    %% Core Runtime Modules
    subgraph "Core Runtime Modules"
        direction TB
        GitResolver["Git Resolver<br>(shaman-git-resolver)"]:::core
        Agents["Agent Registry<br>(shaman-agents)"]:::core
        Executor["Agent Execution Engine<br>(shaman-agent-executor)"]:::core
        JSONRPC["JSON-RPC Handler<br>(shaman-jsonrpc)"]:::core
        Transport["Transport Layer<br>(shaman-a2a-transport)"]:::core
        ClientSDK["Client SDK<br>(shaman-a2a-client)"]:::core
        LLMCore["LLM Core<br>(shaman-llm-core)"]:::core
        VercelAdapter["Vercel Adapter<br>(shaman-llm-vercel)"]:::core
        ToolRouter["Tool Router<br>(shaman-tool-router)"]:::core
        Types["Shared Types<br>(shaman-types)"]:::core
        Config["Config Loader<br>(shaman-config)"]:::core
        DBModule["DB Module<br>(shaman-db)"]:::core
    end

    %% Infrastructure Layer
    subgraph "Infrastructure"
        direction TB
        Postgres["PostgreSQL<br>(shaman-db infra)"]:::infra
        Redis["Redis + BullMQ"]:::infra
        Observability["Observability<br>(shaman-observability)"]:::infra
        Security["Security<br>(shaman-security)"]:::infra
        Logging["Logging<br>(shaman-logger)"]:::infra
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Foreman["Foreman Workflow Service"]:::external
        Permiso["Permiso RBAC (planned)"]:::external
        Kratos["Ory Kratos (planned)"]:::external
    end

    %% Connections: GraphQL
    GraphQL -->|"Reads/Writes"| Postgres
    GraphQL -->|"BullMQ Job"| Redis
    GraphQL -->|"Enforce Auth"| Security
    GraphQL -->|"Emit Metrics/Traces"| Observability
    GraphQL -->|Orchestrate| Foreman

    %% Connections: Worker
    Worker -->|"Subscribe Jobs"| Redis
    Worker -->|"Fetch Code"| GitResolver
    Worker -->|"Resolve Agents"| Agents
    Worker -->|"Execute Logic"| Executor
    Executor -->|"Call LLM"| LLMCore
    LLMCore -->|"Adapter"| VercelAdapter
    Executor -->|"Route Tools"| ToolRouter
    Worker -->|"Write Results"| Postgres
    Worker -->|"Emit Logs/Stats"| Logging
    Worker -->|"Emit Metrics/Traces"| Observability
    Worker -->|Orchestrate| Foreman

    %% Connections: A2A Execution Server
    A2A -->|"JSON-RPC/REST/SSE"| JSONRPC
    A2A -->|"Transport"| Transport
    A2A -->|"Invoke Executor"| Executor
    A2A -->|"Publish Events"| Redis
    A2A -->|"Store State"| Postgres
    A2A -->|"Emit Metrics/Traces"| Observability

    %% Connections: Core Module Dependencies
    GitResolver -->|uses| DBModule
    Agents -->|uses| DBModule
    JSONRPC -->|uses| Transport
    ClientSDK -->|uses| JSONRPC
    Transport -->|uses| ClientSDK
    DBModule -->|enforces RLS| Postgres
    Config -->|provides| GraphQL
    Config -->|provides| A2A
    Config -->|provides| Worker
    Types -->|shared| GitResolver
    Types -->|shared| Executor

    %% Click Events
    click GraphQL "https://github.com/codespin-ai/shaman/tree/main/node/packages/shaman-gql-server"
    click A2A "https://github.com/codespin-ai/shaman/tree/main/node/packages/shaman-a2a-server"
    click Worker "https://github.com/codespin-ai/shaman/tree/main/node/packages/shaman-worker"
    click Postgres "https://github.com/codespin-ai/shaman/tree/main/database/shaman"
    click DBModule "https://github.com/codespin-ai/shaman/tree/main/node/packages/shaman-db"
    click Observability "https://github.com/codespin-ai/shaman/tree/main/node/packages/shaman-observability"
    click Security "https://github.com/codespin-ai/shaman/tree/main/node/packages/shaman-security"
    click Logging "https://github.com/codespin-ai/shaman/tree/main/node/packages/shaman-logger"
    click GitResolver "https://github.com/codespin-ai/shaman/tree/main/node/packages/shaman-git-resolver"
    click Agents "https://github.com/codespin-ai/shaman/tree/main/node/packages/shaman-agents"
    click Executor "https://github.com/codespin-ai/shaman/tree/main/node/packages/shaman-agent-executor"
    click JSONRPC "https://github.com/codespin-ai/shaman/tree/main/node/packages/shaman-jsonrpc"
    click Transport "https://github.com/codespin-ai/shaman/tree/main/node/packages/shaman-a2a-transport"
    click ClientSDK "https://github.com/codespin-ai/shaman/tree/main/node/packages/shaman-a2a-client"
    click LLMCore "https://github.com/codespin-ai/shaman/tree/main/node/packages/shaman-llm-core"
    click VercelAdapter "https://github.com/codespin-ai/shaman/tree/main/node/packages/shaman-llm-vercel"
    click ToolRouter "https://github.com/codespin-ai/shaman/tree/main/node/packages/shaman-tool-router"
    click Types "https://github.com/codespin-ai/shaman/tree/main/node/packages/shaman-types"
    click Config "https://github.com/codespin-ai/shaman/tree/main/node/packages/shaman-config"
    click Foreman "https://github.com/codespin-ai/shaman/tree/main/node/packages/foreman-client"

    %% Styles
    classDef server fill:#D0E8FF,stroke:#0284C7,color:#000
    classDef core fill:#E0F8E0,stroke:#0A662E,color:#000
    classDef infra fill:#FFE0B2,stroke:#E65100,color:#000
    classDef external fill:#F0F0F0,stroke:#666,color:#000
```
