Skip to main content

Engine Microservices

This directory contains standalone Go applications for the ACP Engine microservice deployment model.

The engine is the public REST entrypoint. The unified MCP service can also have a dedicated public ingress for MCP JSON-RPC. All other domain services should remain reachable only through Kubernetes services or the internal Docker Compose network.

Services:

  • auth: authentication, users, realms, memberships, service accounts, realm keys, merchant API-key introspection, and themes.
  • runtime: flows, prompts, sessions, context, agent config, and routing rules.
  • ai: AI chat, AI usage, and centralized text/image provider management.
  • mcp: public MCP JSON-RPC facade plus MCP server management, discovery, routing, proxying, tool execution, and built-in Catalog tools.
  • usage: usage records and usage summaries.
  • catalog: merchant- and store-scoped products, carts, checkouts, orders, and Catalog webhooks.
  • enrichment: internal store Enrichment jobs and runs, merchant provider execution, and separate usage accounting for Manager.
  • data: anonymous commerce, search, and conversation event ingestion plus OpenSearch-backed query and aggregation.
  • safezone: tenant policy resolution, installed Safe Zone health checks, request/response inspection, masking or blocking decisions, and decision-only audit metadata.

Each service:

  • Runs as its own Go application.
  • Uses cmd/server as its entrypoint, matching the standalone service style used by merchant tooling.
  • Reads PORT and DB_URL from the environment.
  • Connects to PostgreSQL directly.
  • Connects to Redis when REDIS_URL is configured.
  • Uses the shared JWT_SECRET for internal authenticated API calls.
  • Accepts signed internal service requests when INTERNAL_SERVICE_SECRET is configured.
  • Emits structured JSON logs with request, trace, user, and realm context.

The public engine reads these internal service URLs:

  • AUTH_SERVICE_URL
  • RUNTIME_SERVICE_URL
  • AI_SERVICE_URL
  • MCP_SERVICE_URL
  • USAGE_SERVICE_URL
  • CATALOG_SERVICE_URL
  • DATA_SERVICE_URL
  • SAFE_ZONE_SERVICE_URL

When a URL is set, the engine proxies matching /api/v1 routes to that service. In the microservice deployment model, these URLs are required and the engine does not own domain feature execution.

The engine also propagates X-Request-ID, X-Trace-ID, traceparent, X-ACP-User-ID, and X-ACP-Realm-ID to internal services so route groups can be tested and traced independently.

Catalog uses Auth at http://auth-service:8081/api/v1 by default and validates merchant keys through /auth/verify and /auth/introspect. Enrichment and Safe Zone are called over the private service network. Data ingestion and query remain public only through the Engine's authenticated /api/v1/data/* boundary.