Architecture Overview

Deployer

Service Architecture

Prodgy is a distributed platform composed of multiple services that communicate with each other. Each service has a specific responsibility and can be deployed independently.

Main Services

Service	Technology	Port	Description
API	Node.js / Express	4000	Main backend — authentication, CRUD, websockets, REST API
Web	React / Vite	3000	Platform frontend (SPA)
Service	Node.js / Express / BullMQ	5000	Queue processing and asynchronous tasks
Engine	Python / FastAPI / LangGraph	8001	AI execution engine — agent and workflow orchestration
Studio	React / Vite	5173	Visual workflow editor
Gateway	Node.js / Express / MCP SDK	3100	MCP server — exposes integrations and tools for external MCP clients
Agentic	Node.js / Express / AI SDK	3200	AI agent orchestrator — multi-step execution with LLM providers
Assistant	C# / .NET 8	443 / 8445	Microsoft Teams bot (calls and messages)
Docs	Astro / Starlight	4321	Platform documentation

Communication Diagram

                    ┌──────────┐
                    │   Web    │ (3000)
                    │  Studio  │ (5173)
                    └────┬─────┘
                         │ HTTP
                    ┌────▼─────┐
                    │   API    │ (4000)
                    └──┬─┬─┬──┘
                       │ │ │
            ┌──────────┘ │ └──────────┐
            │            │            │
      ┌─────▼────┐  ┌───▼────┐  ┌────▼─────┐
      │  Service  │  │ Engine │  │ Supabase │
      │  (5000)   │  │ (8001) │  │ (Postgres)│
      └─────┬─────┘  └───┬────┘  └──────────┘
            │             │
       ┌────▼─────┐       │
       │  Redis   │◄──────┘
       │  (6379)  │
       └──────────┘

      ┌───────────┐
      │  Gateway  │ (3100)
      │  (MCP)    │──── HTTP ──→ API (4000)
      └───────────┘

      ┌───────────┐
      │  Agentic  │ (3200)
      │  (AI SDK) │──── HTTP ──→ API (4000)
      └───────────┘

      ┌───────────┐
      │ Assistant  │ (443/8445)
      │  (.NET)    │──── HTTP ──→ API (4000)
      └─────┬──────┘             Redis (6379)
            │
      Microsoft Teams

Service Responsibilities

API (Backend)

The platform’s central service. All requests from frontends and external integrations go through it.

Authentication and authorization (JWT + API Tokens)
REST API for all resources (agents, integrations, knowledge, etc.)
WebSocket via Socket.io for real-time updates
Organization, product, and user management
Communication with Supabase (PostgreSQL)
Proxy to Engine and Service

Web (Frontend)

React application that provides the platform interface.

Monitoring dashboard
Chat playground with agents
Integration and knowledge base management
Admin panel
Light/dark theme

Service (Queues)

Processes asynchronous tasks using BullMQ with Redis as broker.

Data pipeline processing
Document import and indexing
Background task execution
Automatic retries with configurable backoff

Engine (AI Engine)

AI agent execution engine written in Python.

Agent orchestration via LangGraph
Semantic search with embeddings (pgvector)
Integration with LLM providers (OpenAI, Anthropic, Google)
Workflow and MCP tool execution

Studio (Workflow Editor)

React application for visual agent workflow creation.

Drag-and-drop workflow editor
Node and connection configuration
Workflow preview and testing
Available only to system users

Gateway (MCP Server)

MCP server that exposes Prodgy integrations and tools for external MCP clients (Claude Code, Cursor, Windsurf, etc.).

MCP protocol via HTTP (StreamableHTTP transport)
Bridge between external AI clients and the Prodgy integration ecosystem
Platform tools (knowledge search, agents, integration catalog)
Dynamic integration tools (loaded from the organization’s active integrations)
Communication with the API via service tokens and user tokens

Agentic (Agent Orchestrator)

AI agent orchestration service using Vercel AI SDK.

Multi-step agent execution with streamText and generateText
Support for multiple LLM providers (OpenAI, Azure OpenAI, Anthropic, Google)
Streaming (SSE) and direct execution endpoints
Automatic agent discovery per workspace
Dynamic integration tool loading via API

Assistant (Teams Bot)

.NET service for Microsoft Teams integration.

Messages and calls via Bot Framework
Real-time audio transcription
Task scheduling via Redis
Requires SSL certificate and Azure AD

Databases

PostgreSQL (Supabase)

The platform’s primary database.

Aspect	Detail
Provider	Supabase (managed PostgreSQL)
Extensions	pgvector (embeddings), UUID, JSONB
Authentication	JWT (anon key + service role key)
Access	Via Supabase client (Node.js and Python)

Redis

Cache and queue broker.

Aspect	Detail
Version	7+ (Alpine)
DB 0	BullMQ queues (Service)
DB 1	Cache and scheduling (Assistant)
Persistence	AOF (Append-Only File)

Inter-Service Communication

Authentication between services is done via static tokens in headers:

Communication	Header	Environment Variable
Any → API	`X-Api-Key`	`PRODGY_API_TOKEN`
Service → Engine	`X-Api-Key`	`PRODGY_ENGINE_TOKEN`
API → Service	`X-Api-Key`	`PRODGY_SERVICE_TOKEN`
Gateway → API	`X-Api-Key`	`PRODGY_API_TOKEN`
Agentic → API	`X-Api-Key`	`PRODGY_API_TOKEN`
Assistant → API	`X-Api-Key`	Configured in `appsettings.json`