Runtime Topology and Flow

Runtime Nodes

• apps/web serves operator/portal interfaces and proxies admin config requests.
• apps/gateway handles API ingress, authn/authz, tenant scope, idempotency, and orchestration.
• Outbox + Job workers run from gateway package scripts and process async workload.
• AgentField control plane + worker nodes execute reasoners/skills for automation workflows.

Dev-only Runtime Mocks

• apps/agentfield-mock is for local contract testing only.
• apps/status-mock is for local telemetry/status compatibility testing only.
• Staging/production must not route core runtime dependencies to mock services.

Primary Request and Event Paths

1. Client or automation sends API request to gateway.
2. Gateway middleware enforces correlation ID, auth context, role checks, and tenant boundary.
3. Resource mutations and async jobs are written to PostgreSQL with idempotency controls.
4. Agent executions are queued to control plane through execute adapter.
5. Workflow completion webhooks update execution/audit records.
6. Telemetry ingestion routes events to outbox and dispatches reasoners asynchronously.

Route Registration Order

The server wires middleware and route modules in this order:

• apps/gateway/src/server.ts
• Health + OpenAPI
• Resource CRUD
• Edge policy
• Telemetry routes
• Execution routes
• Integrations/adapters
• Settings and import/export

Health Surfaces

• GET /health
• GET /.well-known/engine-status

These are implemented in apps/gateway/src/routes/health.ts.