System Manual
Architecture
The cooperating pieces that make up eClips Workforce — the API and orchestrator, the dashboard, the agent and shared packages, and the multi-tenant Supabase layer underneath.
The shape of the system
eClips ships as three products: the Portal (the Workforce app and dashboard), the public website, and a separate consumer product. This manual is about Workforce. Inside Workforce the work is split across a small number of cooperating layers, each with a single clear responsibility.
Clients
API · Express service
Public /v1 REST surface
Org-scoped keys · auth
LangGraph orchestrator
start router → Center / Reader → specialist → exit
Agents & engine · packages
agents
fleet · harness · evaluator · trust manager · credit middleware
shared
MODEL_MAP · CONFIDENCE_THRESHOLDS · PLANS · AUTONOMY_GATES
mcp & reach
connector registry · browser tool
Supabase · multi-tenant, Row-Level Security
Every row scoped to an organization — one org can never read or write another's data.
The layers
| API | Express service exposing the public /v1 REST surface and hosting the LangGraph orchestrator that drives every run. |
| Orchestrator | A LangGraph StateGraph: a start router, the Center router, the Reader, 90+ specialist nodes, and integration / triage terminals. |
| Dashboard | Next.js app where operators configure agents and rules, work the triage inbox, review run traces, manage integrations, and track usage. |
| agents package | The fleet itself plus the reliability harness, the evaluator, the trust manager, and the credit-metering middleware. |
| shared / engine packages | Shared types (AgentType, TrustLevel), the MODEL_MAP routing table, the billing / credit rules, and confidence thresholds used across the API and agents. |
| Supabase | Postgres for persistence, plus Auth and Storage, with multi-tenant Row-Level Security isolating every organization. |
The API & the LangGraph orchestrator
The API is an Express service. It exposes a public /v1 REST surface (covered under Security) and hosts the LangGraph orchestrator that drives every run as a state machine. A run never executes an agent directly — it always flows through the compiled graph.
How a run moves through the graph
The graph has a fixed topology. A run enters at a start node and is routed as follows:
- •
Start router
If the caller named a specific agent (and it is a direct-capable type), the run is dispatched straight to that specialist node. A request for the Reader goes to the Reader. Otherwise it goes to the Center. - •
Center or Reader
The Center router decides which specialist should own an ambiguous run and loads that org's configured rules for the agent. The Reader handles high-volume document extraction before routing. - •
One specialist node
The run lands on exactly one specialist, which executes under the harness and produces an output with a confidence score and a triage flag. - •
Integration or triage exit
If the agent is confident (score ≥ 0.85) and did not flag triage, the run exits to integration and acts. Otherwise it exits to triage for a human.
AGENT_REGISTRY array; each entry declares a node key, an agent type, whether it can bypass Center, and the agent instance. The graph wires the node and its edges automatically from that array — no graph surgery required.The dashboard
The dashboard is a Next.js app — the human governance surface. From it, operators author the rules each agent follows, watch the triage inbox and approve/reject/redirect exceptions, open a run's trace to see which model ran and why, connect integrations, manage trust promotions, and track credit usage against the plan's budget.
The agents, engine & shared packages
The runtime that the orchestrator drives lives in a few packages:
- agents — every specialist agent class, the harness, the evaluator, the trust manager, and the credit-metering middleware.
- shared — the single source of truth for cross-cutting facts: the
MODEL_MAP(agent → model),CONFIDENCE_THRESHOLDS, thePLANSand credit multipliers, and theAUTONOMY_GATEStrust ladder. Keeping these here means the API, the agents, and the marketing site all read the same numbers. - mcp & reach — the integration surfaces agents act through: the MCP connector registry and the Reach browser tool (both covered under Integrations).
Supabase: multi-tenant persistence & RLS
Supabase provides Postgres persistence, Auth, and Storage. Every table holding customer data — runs, triage items, trust profiles, the credit ledger, circuit-breaker state, documents — is scoped to an organization and protected by Row-Level Security (RLS). One org can never read or write another's data; all agent state (circuit breakers, trust, usage) is keyed by org.
Example · Where a single run touches the stack
An invoice arrives via /v1. The Express API authenticates the org-scoped key, writes an agent_runs row, and invokes the orchestrator. The start router sends it to invoice_processor; the harness checks credit_usage_periods and agent_circuit_breakers, runs the agent, and on success records a row in credit_ledger. The orchestrator updates the run's status to completed. Every one of those rows is RLS-scoped to the invoice's organization.