Packages

Packages overview

Argus is an npm workspace of ten packages under packages/, each with one job. Every cross-package type lives in @argus/shared — the contract package — and everything infra-shaped sits behind an interface there, which is why the whole service builds, runs, and tests offline.

Dependency graph

Arrows read "depends on". Every package depends on @argus/shared — those nine edges are omitted so the real structure is visible.

flowchart TD
  ingress["@argus/ingress<br/>webhook front door"] --> ado["@argus/ado<br/>ADO client"]
  ingress --> db["@argus/db<br/>state store"]
  mcp["@argus/mcp-ado<br/>5-tool MCP server"] --> ado
  worker["@argus/worker<br/>agent runtime"] --> ado
  worker --> db
  worker --> mcp
  worker --> queue["@argus/queue<br/>per-PR sessions"]
  worker --> rules["@argus/rules<br/>rules registry"]
  evals["@argus/evals<br/>golden-PR harness"] --> worker
  evals --> rules
  docs["@argus/docs-server<br/>this site"]
  shared["@argus/shared — contracts (imported by all of the above)"]

Figure 1 · The workspace dependency graph — every package also depends on @argus/shared, edges omitted for legibility.

The ten packages

Package	One line	Page
`@argus/shared`	Every cross-package contract: jobs, findings, queue, rules, `AdoClient`, runner, checkout, config, redacting logger	shared
`@argus/ingress`	Fastify webhook endpoint: auth, loop filter, actionability, dedup, event→job mapping, fast 202	ingress
`@argus/queue`	`MemoryQueue` and `ServiceBusQueue` — strict per-PR ordering, cross-PR parallelism, dead-lettering	queue
`@argus/worker`	The per-job review pipeline: rules → checkout → tier → runner → validate → post → audit	worker
`@argus/ado`	`RestAdoClient` (Entra primary, PAT fallback) and `FakeAdoClient` for offline runs	ado
`@argus/mcp-ado`	The five-tool ADO MCP server — the only mutation path, with budgets and typed refusals	mcp-ado
`@argus/rules`	Registry-routed rule packs, repo-instructions discovery, prompt assembly + `prompt_sha`, publish/drift	rules
`@argus/db`	The `reviewer` Postgres schema: migrations (postgrator) and typed repositories	db
`@argus/evals`	Golden-PR eval harness: corpus, deterministic scoring, baseline regression gate, optional Opik export	evals
`@argus/docs-server`	Static serving for this documentation site (fastify + `@fastify/static`)	docs-server

Composition roots live in bin/ (not a package): argus-ingress.ts, argus-worker.ts, argus-rules.ts, argus-evals.ts, argus-migrate.ts, argus-docs.ts, with every infra/mock switch in bin/lib/wiring.ts. One container image runs all of them by CMD override.

Workspace conventions

Contracts are imported, never redefined — if a type crosses a package boundary, it lives in @argus/shared.
Tests live in src/__tests__/, never beside production code; they run on in-memory fakes (pg-mem, FakeAdoClient, MockRunner) — no network, no credentials.
zod at every boundary — webhook bodies, job payloads, model output, config, rule-pack front-matter.

← Deployment shared →