Safeguard Work-Order Agent Ecosystem

Architecture

Architecture — Work-Order Agent Ecosystem

Pipeline (live stack)

HTTP POST /work-orders (server.mjs)
      │
      ▼
┌───────────────┐   classification (category, priority, fields, confidence)
│  Classifier   │
└───────────────┘
      │
      ▼
┌───────────────┐  routing (queue, crew, region, SLA)
│    Router     │
└───────────────┘
      │
      ▼
┌───────────────┐  VALID │ NEEDS_REVIEW │ REJECT   (duplicate check = DB query)
│   Validator   │───────────────┬───────────────────┐
└───────────────┘               │                   │
      │ VALID                   │ NEEDS_REVIEW       │ REJECT
      ▼                          ▼                   ▼
┌───────────────┐        ┌──────────────┐   ┌──────────────┐
│   Actioner    │        │ human excep- │   │  rejected +  │
└───────────────┘        │ tion queue   │   │  audited     │
   │            │        └──────────────┘   └──────────────┘
   │ gRPC wire  │ repository
   ▼            ▼
real gRPC     real PostgreSQL
DispatchSvc   (work_orders, audit_log, dispatch_records)

Design principles

Agents are pure where possible. Classifier and router are pure functions;

the validator is pure given a pre-computed duplicate flag; only the actioner performs side effects, through the gRPC + repository seams.

Confidence drives autonomy. The classifier emits calibrated confidence;

the validator converts low confidence into a human exception.

Safety is conservative by default. Ambiguity, missing data, over-budget,

and duplicates route to a human. False-auto-action rate is a MUST_PASS metric pinned at 0.

Real, contract-first integration. Dispatch is a real gRPC/HTTP2 call

defined by proto/dispatch.proto; persistence is real PostgreSQL via a repository interface. The same interfaces target a Go gRPC service and an external Postgres/Oracle server.

Everything is auditable + durable. Every order produces one append-only

audit_log row; state lives in work_orders; dispatches in dispatch_records; all durable on disk.

Module map

Module	Responsibility
`src/schema.mjs`	domain vocabulary + dispatch-payload contract
`src/agents/classifier.mjs`	classify + extract + confidence
`src/agents/router.mjs`	routing policy
`src/agents/validator.mjs`	business-rule safety boundary
`src/agents/actioner.mjs`	dispatch / exception / reject + side effects
`src/orchestrator.mjs`	end-to-end pipeline + HITL metric
`src/config.mjs`	environment-based configuration
`src/bootstrap.mjs`	selects external vs. in-process; wires the pipeline
`src/db/database.mjs`	PostgreSQL (external via DATABASE_URL, or PGlite)
`src/integrations/grpc-server.mjs`	in-process Node gRPC service (fallback/dev)
`src/integrations/grpc-gateway.mjs`	real gRPC dispatch client
`src/integrations/repository.mjs`	PostgreSQL work-order repository
`dispatch-service/`	external Go gRPC dispatch service (+ Dockerfile)
`docker-compose.yml`	external PostgreSQL + Go service
`proto/dispatch.proto`	gRPC dispatch contract (shared Node + Go)
`src/http-app.mjs`	HTTP request handler
`server.mjs`	HTTP ingest service
`src/synth.mjs`	seeded labeled corpus generator
`src/evaluation.mjs`	scores output vs. ground truth

Production integration path

Go gRPC service: implement proto/dispatch.proto in Go; point the gateway

address at it. Wire-compatible, no agent changes.

External Postgres / Oracle: set DATABASE_URL (Postgres) or supply an

Oracle adapter behind the same repository interface.

LLM classifier: implement classify() with an LLM, preserving the

confidence + reasoning contract.

See run-deploy-instructions.md.