Service Dependency Graph

This page documents which service calls which, what protocols they use, and the port assignments for the entire platform.

Dependency Map


                          +-----------+
                          |  Frontend |
                          |  :3000    |
                          +-----+-----+
                                |
                          HTTP (all API calls)
                                |
                                v
                         +------+------+
                         | API Gateway |
                         |   :8000     |
                         +------+------+
                                |
          +--------+--------+---+---+--------+--------+--------+
          |        |        |       |        |        |        |
          v        v        v       v        v        v        v
     +----+---+ +-+----+ +-+---+ +-+----+ +-+----+ +-+---+ +--+---+
     | Orch   | |Apprvl| | KG  | |Ingest| |Compl.| |Flar.| | Auth |
     | :8001  | |:8004 | |:8003| |:8005 | |:8006 | |:8007| | :8009|
     +---+----+ +------+ +--+--+ +--+---+ +--+---+ +--+--+ +------+
         |                   |       |        |        |
         +---+---+---+      |       |        |        |
         |   |   |   |      |       |        |        |
         v   v   v   |      |       v        v        |
       Mem  KG  Appr |    Postgres KG:8003 Postgres   |
       :8002:8003:8004|                                |
         |   |   |    |                                v
         v   v   v    v                              Kafka
       Redis PG  PG  PG

Service-to-Service Communication

All inter-service communication uses synchronous HTTP REST calls, except for the ingestion service which also publishes events to Kafka asynchronously.

API Gateway (Go, port 8000)

The gateway routes all /api/v1/* requests to backend services:

Route Pattern	Target Service	Target Path
`/api/v1/agents/{id}/execute`	Orchestration (:8001)	`/execute`
`/api/v1/agents/{id}/stream/{conv}`	Orchestration (:8001)	`/conversations/{conv}/stream`
`/api/v1/conversations/*`	Orchestration (:8001)	`/conversations/*`
`/api/v1/compliance/summary`	Orchestration (:8001)	`/compliance/summary`
`/api/v1/compliance/matrix`	Orchestration (:8001)	`/compliance/matrix`
`/api/v1/compliance/charts/*`	Orchestration (:8001)	`/compliance/charts/*`
`/api/v1/compliance/assess*`	Orchestration (:8001)	`/compliance/assess*`
`/api/v1/checklists*`	Orchestration (:8001)	`/checklists*`
`/api/v1/rules*`	Orchestration (:8001)	`/rules*`
`/api/v1/workspaces/*`	Orchestration (:8001)	`/workspaces/*`
`/api/v1/approvals*`	Approval (:8004)	`/approvals*`
`/api/v1/graph/*`	Knowledge Graph (:8003)	`/entities/`, `/context/`
`/api/v1/impact/*`	Knowledge Graph (:8003)	`/impact/*`
`/api/v1/entities*`	Knowledge Graph (:8003)	`/managed-entities*`
`/api/v1/entity-types*`	Knowledge Graph (:8003)	`/entity-types*`
`/api/v1/admin/*`	Knowledge Graph (:8003)	`/admin/*` (admin role required)
`/api/v1/detection-rules*`	Knowledge Graph (:8003)	`/event-detection-rules*` (power_user/admin)
`/api/v1/ingest/*`	Ingestion (:8005)	`/ingest/*`
`/api/v1/compliance/*`	Compliance (:8006)	`/compliance/*` (legacy endpoints)
`/api/v1/events*`	Flaring (:8007)	`/events*`
`/api/v1/flare-events*`	Flaring (:8007)	`/flare-events*`
`/api/v1/flaring/*`	Flaring (:8007)	`/flaring/*`
`/api/v1/prompts*`	Agent Config (:8010)	`/prompts*`
`/api/v1/auth/*`	Auth (:8009)	`/auth/*`

The gateway validates JWT tokens by decoding them locally using the shared JWT_SECRET (read from the Authorization header or the aegis_token cookie). The auth service is called only for token generation at login, not for every request validation.

Orchestration Engine (Python, port 8001)

The orchestration engine is the most connected service. During agent execution, it calls:

Dependency	Protocol	Purpose
Memory Service (:8002)	HTTP	Fetch working memory, search episodic memory, check/mark injection ledger
Knowledge Graph Service (:8003)	HTTP	Assemble Tier 3.5 graph context for skill injection, tool call queries
Approval Service (:8004)	HTTP	Create HITL approval requests, check approval status
Agent Config Service (:8010)	HTTP	Resolve and render system prompts at conversation start (fallback to hardcoded if unavailable)
PostgreSQL	TCP	Direct DB access for skill registry, conversations, checklists, compliance status, rules
OpenAI API	HTTPS	LLM calls via LiteLLM (gpt-4o, gpt-4o-mini), embeddings

Memory Service (Python, port 8002)

Dependency	Protocol	Purpose
Redis	TCP	Working memory (Hash), injection ledger (Hash)
PostgreSQL	TCP	Episodic memory storage and pgvector similarity search
OpenAI API	HTTPS	Generate embeddings (text-embedding-3-small, 1536 dimensions) for episodic storage/search

Knowledge Graph Service (Python, port 8003)

Dependency	Protocol	Purpose
PostgreSQL (AGE)	TCP	All graph operations via openCypher queries through the Apache AGE extension
PostgreSQL (relational)	TCP	Entity type definitions, relationship rules, detection rules (relational tables)

Ingestion Service (Python, port 8005)

Dependency	Protocol	Purpose
Kafka	TCP	Publish entity extraction events to the `entity-extraction-worker` topic

Compliance Monitor (Python, port 8006)

Dependency	Protocol	Purpose
Knowledge Graph Service (:8003)	HTTP	Cypher queries for compliance checks

Flaring Monitor (Python, port 8007)

Dependency	Protocol	Purpose
PostgreSQL	TCP	Direct DB access for operational events, flare events, authorizations
Knowledge Graph Service (:8003)	HTTP	Entity lookups

Agent Config Service (Python, port 8010)

Dependency	Protocol	Purpose
PostgreSQL	TCP	Prompt templates, versions, namespaces, audit trail
Redis	TCP	Runtime resolution cache (active 5-min TTL, pre-prod 60s TTL)

Auth Service (Python, port 8009)

Dependency	Protocol	Purpose
None	—	Self-contained. Uses in-memory dev user map. Production would use PostgreSQL.

Startup Order

Services must start in dependency order. The start-all.sh script enforces this:

Infrastructure: PostgreSQL, Redis, Kafka (Docker Compose)
Core services: Memory Service, Knowledge Graph Service, Approval Service, Agent Config Service
Application services: Orchestration Engine, Ingestion Service, Compliance Monitor, Flaring Monitor
Auth service: Auth Service
Gateway: API Gateway (Go)

If you start the orchestration engine before the memory service or knowledge graph service are ready, agent execution will still work — failed HTTP calls to those services are caught and logged as warnings, with graceful fallbacks (empty memory context, no graph context).

Port Assignment Table

Port	Service	Language
3000	Frontend (Next.js)	TypeScript
5432	PostgreSQL 15	—
6379	Redis 7	—
8000	API Gateway	Go
8001	Orchestration Engine	Python
8002	Memory Service	Python
8003	Knowledge Graph Service	Python
8004	Approval Service	Python
8005	Ingestion Service	Python
8006	Compliance Monitor	Python
8007	Flaring Monitor	Python
8009	Auth Service	Python
8010	Agent Config Service	Python
9092	Kafka	—