System Manual
Architecture
The parts of eClips Workforce and how they fit: the API and its orchestrator, the dashboard, the agent and shared packages, and the multi-tenant Supabase database underneath.
The shape of the system
Workforce is split into a few layers, and each has one job.
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 is scoped to an organization, so one org cannot 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, the specialist nodes, and the integration and triage exits. |
| 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 calls an agent directly. It always goes 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 from that array.The dashboard
The dashboard is a Next.js app, and it is where people manage the agents. Operators write the rules each agent follows and work the triage inbox, approving, rejecting or redirecting exceptions. They can open a run's trace to see which model ran and why, connect integrations, set trust levels, and track credit usage against the plan.
The agents, engine & shared packages
The runtime that the orchestrator drives lives in a few packages:
- The
agentspackage holds every specialist agent class, the harness, the evaluator, the trust manager, and the credit-metering middleware. - The
sharedpackage holds the facts every other part reads: theMODEL_MAP(agent to model),CONFIDENCE_THRESHOLDS, thePLANSand credit multipliers, and theAUTONOMY_GATESfor earned autonomy. The API and the agents read the same numbers from here. - The
mcpandreachpackages are how agents act on other systems: the MCP connector registry and the Reach browser tool. Both are covered under Integrations.
Supabase: multi-tenant persistence & RLS
Supabase provides the Postgres database, Auth and Storage. Every table that holds 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 cannot read or write another's data, and all agent state 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.