Benefits Deduction Calculator & Payroll Sync
Build an internal tool that calculates each employee's per-paycheck benefit deductions from their elections, reconciles them against the payroll file, and flags discrepancies before HR exports corrections.
A login-protected tool that computes per-paycheck deductions (with pre/post-tax handling, employer share, and mid-period proration), reconciles them against your payroll file, flags discrepancies, routes corrections through an HR approval gate, and exports a clean deduction-correction CSV for payroll.
Before you start
- A free Vercel account
- A free Supabase account
- A free Resend account
- Your approved benefit elections, plan costs, and the pay-period calendar (a spreadsheet is fine)
- A recent payroll deduction file to reconcile against (CSV export is fine)
The problem this kills
Every pay cycle, the same tickets land in your inbox: "Why was my deduction wrong?" Someone's medical premium doubled after they added a dependent. A new hire's first check skipped their dental entirely. A mid-month plan change got prorated by hand - or didn't. Pre-tax and post-tax amounts got mixed up. And nobody catches it until the employee complains, the carrier invoice doesn't match, or finance asks why the deduction totals drifted.
The math itself isn't hard. What's hard is doing it the same way, every employee, every period, and catching the mismatches against what payroll actually deducted - before they snowball into months of corrections, retro adjustments, and angry emails.
This tool does the calculation the same way every time, lines it up against your real payroll file, and puts a human in front of every correction before it goes anywhere.
What you'll build
A small, secure web app that:
- Loads your approved elections (who's enrolled in what), the plan costs and contribution splits (employee share vs employer share, pre-tax vs post-tax), and your pay-period calendar.
- Computes each employee's per-paycheck deduction - including mid-period proration when someone starts or stops a plan partway through a period, and the right amount when a plan is spread over a different number of paychecks.
- Imports your current payroll deduction file and reconciles the calculated amounts against what payroll actually has.
- Flags every discrepancy - too high, too low, missing, or extra - with the dollar gap and a plain-language reason.
- Routes the proposed corrections through a human approval gate: HR/payroll reviews each one, confirms any proration, and approves before anything is committed.
- Exports a clean deduction-correction CSV in the exact columns your payroll system expects.
This is not tax advice and it doesn't file anything - it's a calculator and a reconciliation checklist with a paper trail.
What's inside the Implementation Plan
The plan is a runbook you paste into an AI coding agent (Claude Code), which then builds the tool for you step by step. You don't write code - you answer questions and paste prompts.
It starts by interviewing you about your business. Before it builds anything, the agent asks how your benefits actually work: which plans you offer, how costs and employer contributions are split, whether amounts are pre-tax or post-tax, how many paychecks each deduction is spread over, how you handle mid-period changes, what your employee IDs and plan codes look like, and the exact columns in your payroll file. Then it reads back a short tailored spec, you give a thumbs-up, and it shapes the data model, the proration rules, and every later step around your answers - not a generic template.
After that, the plan walks through setting up your accounts, building the database with security baked in, importing your elections and payroll file, running the calculation and reconciliation, the HR approval screen, the audit trail, and the CSV export - each step ending with a ready-to-paste prompt.
The governance it includes (this is the point)
- Login so only your team can open the tool.
- Row-level security so each organization only ever sees its own employees and data.
- A complete audit trail - who calculated, who reviewed, who approved, who exported, and when.
- A hard human-in-the-loop approval gate - the tool drafts the deductions and corrections; a person reviews discrepancies and confirms proration, and only then are corrections committed and exported. Nothing flows to payroll automatically.
- Duplicate guards so the same employee + plan + pay period can't be processed or exported twice.
Who it's for
Benefits administrators and payroll specialists who chase "why was my deduction wrong?" tickets every cycle, reconcile by squinting at two spreadsheets side by side, and want the math done the same way every time with discrepancies caught early - and a clean record of every correction.
You've got this. Paste the first prompt and let the agent interview you.