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/connectors*`	Connector (:8011)	`/connectors*` (the `.../status` and execute paths are service-internal — NotFound’d at the gateway)
`/api/v1/auth/*`	Auth (:8009)	`/auth/*`

The gateway fast-rejects by decoding the JWT locally with the shared JWT_SECRET (read from the Authorization header or the aegis_token cookie), then re-resolves authorization fresh from the auth service via POST /auth/resolve on every authenticated request (R42a/b — ~5s per-user cache, stale-while-revalidate). Authorization is therefore DB-fresh at the perimeter, not stale JWT claims.

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 skills, routers, rules, personas, prompts, and Platform Settings — the runtime source of truth for agent behavior. An unseeded tenant runs skill-less (general mode); there is no hardcoded prompt fallback (R35 P6).
Sandbox Runner	unix socket	Jailed (nsjail) execution of skill code-block tools
PostgreSQL	TCP	Direct DB access for conversations, checklists, compliance status, rules, snapshots
Anthropic API	HTTPS	LLM calls via LiteLLM — box default `anthropic/claude-sonnet-5`
OpenAI API	HTTPS	Episodic-memory embeddings (`text-embedding-3-small`); box OpenAI key is dead so embeddings degrade

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	Skill definitions, routers (`skill_routers`/`skill_router_map`/`skill_description_versions`), rule definitions, personas, prompt templates/versions, entity-type definitions, Platform Settings, audit trail. Self-applies its migrations on every boot.
Redis	TCP	Runtime resolution cache (active 5-min TTL, pre-prod 60s TTL)

Connector Service (Python, port 8011)

Dependency	Protocol	Purpose
PostgreSQL	TCP	Connector catalog (`integration_connectors`), schema snapshots, execution log, HMAC-signed audit rows
Secret store	HTTPS / file	Credential custody — GCP Secret Manager (`AEGIS_SECRET_BACKEND=gcp`) or a local Fernet file store (`dev`)
External tenant databases	TCP/TLS	Outbound postgres/snowflake connections for probes and discovery — always through the default-deny egress chokepoint (`egress.py`)

Auth Service (Python, port 8009)

Dependency	Protocol	Purpose
PostgreSQL	TCP	`users`, bcrypt password hashes, and the RBAC tables (`roles`, `role_permissions`, `user_roles`, `user_invites`) it owns via its boot-time migration runner. Backs `/auth/token`, `/auth/resolve`, sessions, invites, and admin user lifecycle.

The gateway (and Caddy forward_auth) call POST /auth/resolve on every authenticated request, so the auth service is on the hot path for authorization — not just login. Results are cached ~5s per user with stale-while-revalidate, so an auth-service restart does not 401 the platform.

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
Connector service: Connector Service (R44a — boot-time migrations must converge before it serves)
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	—
5433	operator-demo PostgreSQL (connector-framework dev fixture, Docker)	—
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
8011	Connector Service	Python
(unix socket)	Sandbox Runner	Python
9092	Kafka	—