Skip to main content

docs/architecture.md

Imported Content​

Architecture Overview

Core principles​

  • AgentField-first domain orchestration
  • Workspace-per-client isolation
  • Async-first workflows with machine-verifiable audit evidence
  • GitOps promotion and immutable deployment manifests
  • JWT-authenticated API access with role- and workspace-aware authorization
  • Signed webhook callbacks with replay protection receipts
  • Runtime configuration plane for platform/workspace controls via API + UI
  • Durable outbox pipeline for telemetry-triggered automation
  • No implicit workspace fallback in production paths

Runtime topology​

  • apps/web: four-page IA only (Console, Ops, Portal, Admin Settings) with workspace-explicit URLs and in-page module tabs/queues/forms.
  • apps/gateway: API gateway + orchestration edge
  • AgentField control plane: reasoner and skill execution backend (self-hosted in production)
  • Background workers: outbox dispatcher and job processor
  • Data services: PostgreSQL, Redis, NATS, object storage, OpenSearch
  • Configuration services: platform_settings, workspace_settings, encrypted runtime_secrets
  • Edge plane: anchor-edge-agent deployments on managed endpoints
  • Deployment control plane: app repo (anchor-msp) + ops repo (anchor-msp-ops)

Local/dev profile only:

  • apps/agentfield-mock
  • apps/status-mock

UI operating model (GA)​

  • Console: primary PSA workspace with tabbed modules for CMDB, service delivery, financials, monitoring; includes list/detail/create/lifecycle controls and advanced JSON tools behind collapsible expert mode.
  • Ops: NOC/SOC center with explicit queues (critical alerts, unassigned tickets, SLA risk, failed workflows, failed outbox/jobs), runtime health, and guided alert->ticket->asset/runbook->escalation workflows.
  • Portal: invite-link session handoff (httpOnly cookie), client-scoped ticket/quote/invoice/KB flows, and permission-aware feedback for scoped access.
  • Admin Settings: runtime policy forms, telemetry enrollment/token rotation, adapter secret metadata, and connectivity/test status surfaces.

Request flow​

  1. User or automation calls gateway endpoint.
  2. Gateway verifies authentication, workspace scope, and idempotency headers.
  3. Gateway enqueues execution to AgentField and returns executionId.
  4. Agent skills perform deterministic side effects.
  5. Signed audit credential is persisted and emitted to evidence store.
  6. Completion event triggers webhook and state update.

Event pipeline​

  1. Telemetry ingest persists batch to telemetry_ingest_batches.
  2. Routed actions are stored in outbox_events.
  3. Outbox worker dispatches actions to AgentField reasoners.
  4. Delivery status is tracked as pending, processing, delivered, or failed.

Tenancy model​

  • Dedicated workspace namespace per client.
  • Dedicated DB schema per workspace.
  • Secret references scoped to workspace context.
  • Sensitive CredentialRef payloads envelope-encrypted at rest.
  • Policy checks enforce no cross-workspace reads/writes.