# dinesh1309/payroll-compliance-agent architecture

> Architecture diagram of the GitHub repository dinesh1309/payroll-compliance-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dinesh1309/payroll-compliance-agent
- Repository: https://github.com/dinesh1309/payroll-compliance-agent

## Overview

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.

Main entry points: [`src/agent/orchestrator.ts`](https://github.com/dinesh1309/payroll-compliance-agent/blob/main/src/agent/orchestrator.ts) (Orchestrator), [`app/Demo.tsx`](https://github.com/dinesh1309/payroll-compliance-agent/blob/main/app/Demo.tsx) (Demo flow), [`src/tools/loadBatch.ts`](https://github.com/dinesh1309/payroll-compliance-agent/blob/main/src/tools/loadBatch.ts) (Load batch), [`src/tools/checks/_base.ts`](https://github.com/dinesh1309/payroll-compliance-agent/blob/main/src/tools/checks/_base.ts) (Compliance checks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Next.js app"]
  node_page["Review UI<br/>next page<br/>[page.tsx]"]
  node_demo["Demo flow<br/>ui demo<br/>[Demo.tsx]"]
  node_review_api["Review API<br/>route handler<br/>[route.ts]"]
  node_editable_grid["Editable Grid<br/>[EditableGrid.tsx]"]
  node_donut(("Donut chart<br/>[Donut.tsx]"))
  node_pill["Pill badge<br/>[Pill.tsx]"]
end

subgraph group_src["Core engine"]
  node_cli["CLI entry<br/>command<br/>[cli.ts]"]
  node_orchestrator{{"Orchestrator<br/>agent loop<br/>[orchestrator.ts]"}}
  node_phases["Phases<br/>[phases.ts]"]
  node_triage["Triage<br/>routing logic<br/>[triage.ts]"]
  node_human_gate["Human gate<br/>approval boundary<br/>[humanGate.ts]"]
  node_load_batch["Load batch<br/>ingestion<br/>[loadBatch.ts]"]
  node_checks{{"Compliance checks<br/>rule engine<br/>[_base.ts]"}}
  node_anomalies["Scan anomalies<br/>analysis<br/>[scanAnomalies.ts]"]
  node_liability["Liability<br/>estimator"]
  node_correction["Draft correction<br/>writer<br/>[draftCorrection.ts]"]
  node_report["Build report<br/>report builder<br/>[buildReport.ts]"]
  node_llm_client["LLM client<br/>model adapter<br/>[client.ts]"]
  node_openrouter["OpenRouter<br/>provider adapter<br/>[openrouter.ts]"]
end

subgraph group_data["Policy data"]
  node_state_rules["State rules<br/>policy data<br/>[state-rules.json]"]
  node_sample_batch["Sample batch<br/>fixture<br/>[sample-batch.json]"]
end

node_page -->|"renders"| node_demo
node_demo -->|"edits"| node_editable_grid
node_demo -->|"summarizes"| node_donut
node_demo -->|"labels"| node_pill
node_review_api -->|"runs"| node_orchestrator
node_cli -->|"runs"| node_orchestrator
node_orchestrator -->|"orders"| node_phases
node_orchestrator -->|"routes"| node_triage
node_orchestrator -->|"escalates"| node_human_gate
node_orchestrator -->|"ingests"| node_load_batch
node_load_batch -->|"sample input"| node_sample_batch
node_load_batch -->|"normalizes"| node_anomalies
node_anomalies -->|"feeds"| node_checks
node_checks -->|"applies"| node_state_rules
node_checks -->|"finds violations"| node_liability
node_liability -->|"drafts"| node_correction
node_correction -->|"explains"| node_report
node_report -->|"displays"| node_page
node_report -->|"prints"| node_cli
node_orchestrator -.->|"optionally uses"| node_llm_client
node_llm_client -->|"backs onto"| node_openrouter

click node_page "https://github.com/dinesh1309/payroll-compliance-agent/blob/main/app/page.tsx"
click node_demo "https://github.com/dinesh1309/payroll-compliance-agent/blob/main/app/Demo.tsx"
click node_review_api "https://github.com/dinesh1309/payroll-compliance-agent/blob/main/app/api/review/route.ts"
click node_editable_grid "https://github.com/dinesh1309/payroll-compliance-agent/blob/main/app/components/EditableGrid.tsx"
click node_donut "https://github.com/dinesh1309/payroll-compliance-agent/blob/main/app/components/Donut.tsx"
click node_pill "https://github.com/dinesh1309/payroll-compliance-agent/blob/main/app/components/Pill.tsx"
click node_cli "https://github.com/dinesh1309/payroll-compliance-agent/blob/main/src/cli.ts"
click node_orchestrator "https://github.com/dinesh1309/payroll-compliance-agent/blob/main/src/agent/orchestrator.ts"
click node_phases "https://github.com/dinesh1309/payroll-compliance-agent/blob/main/src/agent/phases.ts"
click node_triage "https://github.com/dinesh1309/payroll-compliance-agent/blob/main/src/agent/triage.ts"
click node_human_gate "https://github.com/dinesh1309/payroll-compliance-agent/blob/main/src/agent/humanGate.ts"
click node_load_batch "https://github.com/dinesh1309/payroll-compliance-agent/blob/main/src/tools/loadBatch.ts"
click node_checks "https://github.com/dinesh1309/payroll-compliance-agent/blob/main/src/tools/checks/_base.ts"
click node_anomalies "https://github.com/dinesh1309/payroll-compliance-agent/blob/main/src/tools/scanAnomalies.ts"
click node_liability "https://github.com/dinesh1309/payroll-compliance-agent/blob/main/src/tools/estimateLiability.ts"
click node_correction "https://github.com/dinesh1309/payroll-compliance-agent/blob/main/src/tools/draftCorrection.ts"
click node_report "https://github.com/dinesh1309/payroll-compliance-agent/blob/main/src/tools/buildReport.ts"
click node_llm_client "https://github.com/dinesh1309/payroll-compliance-agent/blob/main/src/llm/client.ts"
click node_openrouter "https://github.com/dinesh1309/payroll-compliance-agent/blob/main/src/llm/openrouter.ts"
click node_state_rules "https://github.com/dinesh1309/payroll-compliance-agent/blob/main/data/state-rules.json"
click node_sample_batch "https://github.com/dinesh1309/payroll-compliance-agent/blob/main/data/sample-batch.json"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_page,node_demo,node_review_api,node_editable_grid,node_donut,node_pill toneBlue
class node_cli,node_orchestrator,node_phases,node_triage,node_human_gate,node_load_batch,node_checks,node_anomalies,node_liability,node_correction,node_report,node_llm_client,node_openrouter toneAmber
class node_state_rules,node_sample_batch toneMint
```

## Components

### Next.js app

Browser-facing review UI and API route.

- [Review UI](https://github.com/dinesh1309/payroll-compliance-agent/blob/main/app/page.tsx): next page · Browser entry and main screen for the compliance review experience. · `app/page.tsx`
- [Demo flow](https://github.com/dinesh1309/payroll-compliance-agent/blob/main/app/Demo.tsx): ui demo · Interactive demo wrapper that feeds the review experience. · `app/Demo.tsx`
- [Review API](https://github.com/dinesh1309/payroll-compliance-agent/blob/main/app/api/review/route.ts): route handler · Server endpoint that invokes the shared review workflow from the browser. · `app/api/review/route.ts`
- [Editable Grid](https://github.com/dinesh1309/payroll-compliance-agent/blob/main/app/components/EditableGrid.tsx): Interactive batch editing surface used by the UI. · `app/components/EditableGrid.tsx`
- [Donut chart](https://github.com/dinesh1309/payroll-compliance-agent/blob/main/app/components/Donut.tsx): Visual summary component for review results. · `app/components/Donut.tsx`
- [Pill badge](https://github.com/dinesh1309/payroll-compliance-agent/blob/main/app/components/Pill.tsx): Compact status/label UI component. · `app/components/Pill.tsx`

### Core engine

Shared agent, compliance tools, and CLI runtime.

- [CLI entry](https://github.com/dinesh1309/payroll-compliance-agent/blob/main/src/cli.ts): command · Headless terminal entry point for reviewing a batch. · `src/cli.ts`
- [Orchestrator](https://github.com/dinesh1309/payroll-compliance-agent/blob/main/src/agent/orchestrator.ts): agent loop · Coordinates phases, tool calls, escalation, and stop conditions. · `src/agent/orchestrator.ts`
- [Phases](https://github.com/dinesh1309/payroll-compliance-agent/blob/main/src/agent/phases.ts): agent phases · Defines the review stages used by the orchestrator. · `src/agent/phases.ts`
- [Triage](https://github.com/dinesh1309/payroll-compliance-agent/blob/main/src/agent/triage.ts): routing logic · Decides which checks or escalation paths to run. · `src/agent/triage.ts`
- [Human gate](https://github.com/dinesh1309/payroll-compliance-agent/blob/main/src/agent/humanGate.ts): approval boundary · Stops automated action and routes corrections for human approval. · `src/agent/humanGate.ts`
- [Load batch](https://github.com/dinesh1309/payroll-compliance-agent/blob/main/src/tools/loadBatch.ts): ingestion · Parses and normalizes payroll batch input into the shared domain model. · `src/tools/loadBatch.ts`
- [Compliance checks](https://github.com/dinesh1309/payroll-compliance-agent/blob/main/src/tools/checks/_base.ts): rule engine · Deterministic payroll-rule predicates for legality and wage violations. · `src/tools/checks/_base.ts`
- [Scan anomalies](https://github.com/dinesh1309/payroll-compliance-agent/blob/main/src/tools/scanAnomalies.ts): analysis · Finds irregularities in the submitted batch before evaluation. · `src/tools/scanAnomalies.ts`
- [Liability](https://github.com/dinesh1309/payroll-compliance-agent/blob/main/src/tools/estimateLiability.ts): estimator · Computes dollars owed from detected violations. · `src/tools/estimateLiability.ts`
- [Draft correction](https://github.com/dinesh1309/payroll-compliance-agent/blob/main/src/tools/draftCorrection.ts): writer · Generates a human-readable corrective action summary. · `src/tools/draftCorrection.ts`
- [Build report](https://github.com/dinesh1309/payroll-compliance-agent/blob/main/src/tools/buildReport.ts): report builder · Assembles the final plain-English compliance report. · `src/tools/buildReport.ts`
- [LLM client](https://github.com/dinesh1309/payroll-compliance-agent/blob/main/src/llm/client.ts): model adapter · Shared model integration layer with deterministic fallback behavior. · `src/llm/client.ts`
- [OpenRouter](https://github.com/dinesh1309/payroll-compliance-agent/blob/main/src/llm/openrouter.ts): provider adapter · OpenRouter-backed language and judgment provider. · `src/llm/openrouter.ts`

### Policy data

Static batch samples and state-specific rules.

- [State rules](https://github.com/dinesh1309/payroll-compliance-agent/blob/main/data/state-rules.json): policy data · Jurisdiction-specific wage and tip-credit rules. · `data/state-rules.json`
- [Sample batch](https://github.com/dinesh1309/payroll-compliance-agent/blob/main/data/sample-batch.json): fixture · Representative payroll batch used for local review and demo flows. · `data/sample-batch.json`

## Connections

- Review UI → Demo flow: renders · The page composes the demo experience.
- Demo flow → Editable Grid: edits · The demo allows batch rows to be modified before review.
- Demo flow → Donut chart: summarizes · The demo visualizes outcomes with charts.
- Demo flow → Pill badge: labels · Status and issue badges are shown in the UI.
- Review API → Orchestrator: runs · The API route triggers the shared agent workflow.
- CLI entry → Orchestrator: runs · The CLI invokes the same compliance engine headlessly.
- Orchestrator → Phases: orders · The orchestrator advances through defined review phases.
- Orchestrator → Triage: routes · Triage selects which checks and escalation paths apply.
- Orchestrator → Human gate: escalates · Potential corrections are paused for approval.
- Orchestrator → Load batch: ingests · Batch data is loaded before analysis begins.
- Load batch → Sample batch: sample input · The demo/CLI can start from the bundled batch fixture.
- Load batch → Scan anomalies: normalizes · Normalized batch data is scanned for irregularities.
- Scan anomalies → Compliance checks: feeds · Detected irregularities inform compliance evaluation.
- Compliance checks → State rules: applies · Checks use jurisdiction-specific policy data.
- Compliance checks → Liability: finds violations · Rule outcomes flow into liability estimation.
- Liability → Draft correction: drafts · Monetized findings are turned into a proposed correction.
- Draft correction → Build report: explains · The correction text becomes part of the final report.
- Build report → Review UI: displays · The browser UI presents the generated report.
- Build report → CLI entry: prints · The CLI can emit the report in terminal output.
- Orchestrator → LLM client: optionally uses · The agent may call the model for judgment or wording.
- LLM client → OpenRouter: backs onto · OpenRouter is the primary model provider implementation.