dinesh1309/payroll-compliance-agent

1. What this repo is

This is a payroll-compliance review system for hospitality batches. It inspects a submitted payroll run *before* payroll is sent, looking for tip-credit / tipped-minimum-wage problems, then computes dollars owed and drafts a human-readable correction.

2. Two entry points, one shared engine

The same review engine is used from both the browser and the terminal. The browser app lives in app/, while the CLI lives in src/cli.ts and can review data/sample-batch.json headlessly. That shared-core design is important: the UI is just a wrapper around the compliance pipeline.

3. Frontend / demo surface

app/page.tsx, app/Demo.tsx, and components like EditableGrid, Donut, and Pill make the review results visible and interactive. The UI is a Next.js App Router app, and app/api/review/route.ts is the server endpoint that likely bridges the browser trigger to the same review workflow. PostHogProvider suggests lightweight product analytics, but it is not part of the compliance logic.

4. Agent orchestration layer

The agent loop is centered in src/agent/orchestrator.ts, with supporting phase definitions in src/agent/phases.ts, triage logic in src/agent/triage.ts, and a human-approval boundary in src/agent/humanGate.ts. This layer decides *when* to run which checks, when to escalate, and when to stop for human review.

5. Deterministic compliance core

The legal/math core is in src/tools/. This includes loading batches, classifying worker roles, scanning anomalies, estimating liability, drafting corrections, and building the final report. The important architectural boundary is that these tools own the law and the arithmetic; they are not delegated to the model.

6. Rule/check subsystem

Specific payroll rules are implemented as checks under src/tools/checks/: tipCreditLegality, tipPool, makeupPay, notice, and eighty20, plus a shared _base.ts. These represent the actual compliance predicates the agent applies to each batch and are the main source of violation findings.

7. State-specific policy data

data/state-rules.json holds jurisdiction-specific rules, and src/tools/stateRules.ts loads them into the evaluation pipeline. That means the architecture is data-driven for state law variation, which is critical for a multi-location compliance product.

8. Batch ingestion and domain model

src/tools/loadBatch.ts and data/sample-batch.json represent the intake boundary for payroll data. The batch is scanned for anomalies and then normalized into the domain model consumed by the checks, liability estimator, and report builder.

9. LLM boundary

The model integration is isolated in src/llm/client.ts and src/llm/openrouter.ts. Per the README, OpenRouter is used only for judgment and language generation; if no API key is present, the system falls back to deterministic behavior. In other words, the LLM is an explanation layer, not a source of truth for compliance.

10. Output and human-in-the-loop flow

The pipeline culminates in a report (src/tools/buildReport.ts) that explains each issue in plain English and quantifies liability. The human gate ensures corrections are routed for approval rather than auto-applied, which is the key operational boundary in the architecture.

11. Runtime / deployment shape

The project is built on Next.js with Bun as the local/runtime tooling (bun.lock, bun run ...). Production is the standard Next build/start flow, and the README notes Vercel as the intended deployment target.

12. How to draw the diagram

A good architecture diagram would show: user or CLI input → Next.js/API or CLI entry point → agent orchestrator/phase loop → deterministic tools and state rules → optional OpenRouter LLM for wording/judgment → human approval gate → final compliance report/UI display.