Architecture Overview

AEGIS is a domain-neutral, stateful runtime platform for enterprise AI agents. Compliance domains are installable packs, entity types are runtime DB-backed definitions, and agent behavior (skills, routers, rules, prompts, settings) is tenant-configurable data served by agent-config-service. The Texas RRC oil & gas vertical is the first installed vertical — five packs (rule_37, rule_32, form_pr, flaring_monitor, epa_oooob) plus the compliance and flaring dashboards — not the product itself.

Structurally, AEGIS is a microservices platform with 11 HTTP backend services (10 Python + the Go API gateway) plus the socket-only sandbox-runner, a Next.js frontend, and three infrastructure dependencies. All client traffic flows through a single Go API gateway that handles authentication, rate limiting, and CORS.

System Diagram

                            +--------------------+
                            |     Frontend       |
                            |  Next.js 16 :3000  |
                            +--------+-----------+
                                     |
                                     | HTTP/SSE (same-origin /api/v1/*)
                                     v
                            +--------------------+
                            |   API Gateway      |
                            |   Go :8000         |
                            |   JWT auth         |
                            |  Rate limit 600/m  |
                            |  CORS middleware   |
                            +--------+-----------+
                                     |
                 +-------+-----------+----------+--------+
                 |       |           |          |        |
                 v       v           v          v        v
          +------+--+ +--+------+ +-+-------+ ++------+ +--+------+
          | Orch.   | | Approval| | KG      | | Ingest| | Auth    |
          | Engine  | | Service | | Service | | Svc   | | Service |
          | :8001   | | :8004   | | :8003   | | :8005 | | :8009   |
          +----+----+ +---------+ +----+----+ +---+---+ +---------+
               |                       |           |
               +-------+-------+      |           |
               |       |       |      |           |
               v       v       v      |           v
          +----+--+ +--+---+ ++------++       +---+---+
          | Memory| | KG   | |Approval|       | Kafka |
          | :8002 | | :8003| | :8004  |       +-------+
          +---+---+ +--+---+ +--------+
              |         |
              v         v
          +---+---+ +---+---+
          | Redis | | Postgres|
          |  7    | | 15+AGE |
          |       | | pgvec  |
          +-------+ +--------+

          +----------+  +----------+  +----------+  +-----------+
          | Complnce |  | Flaring  |  | AgentCfg |  | Connector |
          | Monitor  |  | Monitor  |  | Service  |  | Service   |
          | :8006    |  | :8007    |  | :8010    |  | :8011     |
          +-----+----+  +-----+---+  +----+-----+  +-----+-----+
                |              |          |              |
                v              v          v              v
          +-----+----+  +-----+---+  +---+------+  +----+-------+
          | KG :8003 |  | Postgres |  | PG+Redis |  | PG + ext.  |
          +----------+  +----------+  +----------+  | data srcs  |
                                                    +------------+

Service Inventory

AEGIS runs 11 HTTP services plus the socket-only sandbox-runner and a frontend:

Infrastructure

All infrastructure runs via Docker Compose on the aegis-network Docker network.

Key Architectural Decisions

Domain-neutral runtime, verticals as packs

The platform core is domain-agnostic. A compliance domain ships as a pack (services/orchestration-engine/src/orchestration/packs/<name>/manifest.yaml, or out-of-tree via PACKS_DIR) declaring its skills, checklist template, and assessment specs. Packs are discovered at startup — adding or removing a pack directory needs zero core edits. Entity types are runtime DB-backed rows (entity_type_definitions), and agent behavior is tenant-configurable data in agent-config-service. RRC oil & gas is simply the first installed vertical.

Single API Gateway

All frontend requests go through the Go API gateway at port 8000. The gateway:

• Validates the JWT (from the Authorization header or aegis_token cookie) on every request (except health checks and public endpoints), then re-resolves authorization fresh from the database via POST /auth/resolve
• Applies per-user rate limiting (600 requests/minute, burst of 100)
• Strips CORS headers from backend responses and applies its own
• Routes requests to the appropriate backend service by URL prefix and stamps identity headers (X-User-Id, X-Roles, X-Tenant-Id, X-Permissions, …)

Since R42d, backend services also verify the perimeter-stamped identity headers via shared/src/aegis_shared/auth.py — the perimeter is no longer the sole authorization layer. See Auth Flow.

LangGraph for Agent Execution

Agent execution follows a compiled LangGraph StateGraph with a defined node pipeline (START → system_prompt_node → memory_node → resume_guard → initial_llm_call → [tool_node → initial_llm_call]* → approval_node → output_format → END). There is a single LLM node — the vestigial synthesis phase was removed in R41 B0. This provides deterministic control flow, shared GraphState across nodes, two-tier budget enforcement, and a tool-calling loop (skill selection runs inside it as ordinary tool calls).

See LangGraph Pipeline for the full pipeline documentation.

Three-Layer Memory

The memory system provides context at three levels:

1. Working memory (Redis): fast key-value store for the current conversation’s scratchpad, entities, and state
2. Episodic memory (pgvector): long-term semantic search over past conversation summaries
3. Injection ledger (Redis Hash): tracks what has been injected into the current conversation to prevent duplicates

See Memory System for details.

Knowledge Graph over Relational Queries

Entity relationships are modeled as a property graph in Apache AGE using openCypher queries, in per-tenant graphs (tenant_<hex>_oilgas). This allows natural modeling of entity relationships, multi-hop traversals for impact analysis, and context assembly by walking the graph from a seed entity. Compliance graph reads use a parameterized {template_id, params} contract (escaped server-side) — raw f-string Cypher is forbidden.

See Knowledge Graph for the schema.

Fail-Closed HITL for All Filings

No regulatory filing can be submitted without human approval. HITL fires from seeded skill require_hitl rules (after_tool_call) and the before_tool_call mutating-tool gate — not from agent or skill identity maps. approval_node is fail-closed: it pauses with status: awaiting_hitl when a mandatory checkpoint cannot be recorded, and never proceeds unreviewed (HITL_BREAK_GLASS restores fail-open for a logged emergency).

Append-Only Audit Trail

The audit_logs table uses PostgreSQL triggers to prevent UPDATE and DELETE operations. Every audit entry includes an HMAC signature for tamper detection.