How codespin-ai/shaman works
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.