Catalis Tax

Overview

A multi-tenant SaaS for county tax collectors: parcels, bills, cash register, solid-waste billing, work orders and reporting. A .NET 10 API on PostgreSQL behind a React 19 admin portal, shipped to AWS ECS through four environments.

239

commits by me

135

pull requests merged

74

Jira tickets delivered

22

months on the platform

Catalis Tax is the second-generation, multi-state version of a county tax system that previously shipped one codebase per state (the "Multi-County Tax Solution v1.0", known internally as Refactored LandNav / PrimeTSR). Version 2.0 rebuilt it as one cloud tenant per customer on a shared .NET and React codebase, with state-specific behaviour isolated behind configuration and per-state modules.

Users are tax collectors and their staff. They look up a parcel, see every bill and payment against it, take money at a cash register, print receipts, run year-end rollovers, import appraiser data and run statutory reports. Mistakes are measured in dollars and audit findings, so correctness is the product.

My role

I joined the team in December 2024 as a full-stack developer working through the outsourced engineering partner, and have shipped across both repositories every month since: the ASP.NET Core API and the React admin portal.

• Full-stack developer in both repositories, December 2024 to present.
• Own tickets end to end: database function, API, UI, pull request, QA follow-up.
• Customers shipped for: Palm Beach County Solid Waste Authority (FL) and Jackson County (MS).
• Team of about fourteen: product owner, BA and SME, lead dev manager, three to five developers, QA, PMO.

The platform in numbers

649

HTTP endpoints

in 95 controllers

450

EF Core entities

168 schema scripts

127

routes in the portal

70 feature folders

59

Combit report templates

51 Florida, 13 Mississippi folders

44

Quartz jobs per tenant

517

xUnit tests

145 files, fully offline

8,172

commits across both repos

since October 2022

4

environments, dev to prod

Impact

Six changes county staff and taxpayers feel every day. Each row shows who it helped, what the screen did before and after, the figure that proves it, and which layers of the stack the work went through.

The challenge

Property tax in the United States is administered by counties, under state law. Florida bills solid-waste assessments through the tax roll and sells tax certificates. Mississippi levies privilege licences by month. Virginia taxes vehicles. South Carolina runs tax sales. Each state has its own penalty and interest schedule, discount periods, installment plans, exemptions and statutory report formats.

The previous product line solved this by forking: one deployment per customer, drifting apart over years. Catalis Tax 2.0 set out to replace that with a single multi-tenant SaaS where a county is a tenant with its own PostgreSQL database and configuration, and the application code is shared. That shape creates the engineering problems this case study is about.

Correctness under variation

A receipt must show the right invoice amount whether the bill was paid in full, in installments, partially, reversed or refunded, and the rules differ by item type and by state.

Reference data at scale

Dozens of lookup tables (DOR codes, hauler codes, boundary tables, rates, rules) that staff maintain themselves and that roll over every tax year.

Files in and out

Appraiser rolls, hauler and CO files, bill-print exports: fixed-width formats from legacy mainframe systems, with an exception workflow when rows fail validation.

Public-sector obligations

ADA and WCAG accessibility, auditability, role and permission control per tenant.

Customers I shipped for

Palm Beach County SWA, FL

Solid Waste Authority billing through the tax roll: boundary tables, hauler codes, installments, work orders and inspections, CO and NAV file imports. Three-year agreement, kickoff August 2024.

Jackson County, MS

Full tax collection: cash register, receipts, privilege licences, bill-print export, supplemental bills, multi-owner parcels.

Vocabulary used on this page

Parcel / PCN

A taxable property and its control number.

Roll

The year's list of parcels, owners and values from the appraiser.

Bill, invoice, installment

A bill becomes an invoice with line values; it may be split into installments.

Millage

Tax rate per thousand dollars of value, per taxing district.

SWA

Solid Waste Authority: collection, disposal and recycling units billed on the roll.

Bump file

The SWA's nightly change file that updates billable items.

Unallocated cash

Money received but not yet applied to a bill, including overpayments.

TRIM

Florida's Truth in Millage notice; the platform exports its data.

System architecture

A browser SPA, a stateless API, a database per tenant, and workers around the edge. The accent line is the path a request takes from a click in the portal to a row in PostgreSQL.

Stateless API

Every request carries a JWT. The tenant is resolved from the token and the request is bound to that tenant's connection string, so the same container image serves every county.

Envelope contract

All endpoints return { Succeeded, Data, Message }. The React API client unwraps it, returning Data or throwing Message, so screens never branch on HTTP shape.

Same image, four stages

Dev builds the image; QA, Stage and Prod promote the exact digest. Configuration is injected at container start, never baked in.

The request pipeline

What happens between a click in the portal and a row in PostgreSQL. The tenant is never a parameter: it comes from the token, binds the connection, and reaches the database as a session setting that row-level security policies can read.

• The security filter reads the user from the token and places TenantId, UsNumb, user name and IP into the request context.
• The unit of work looks up the tenant in the global tenant master and builds that tenant's connection string from a template plus the tenant's own database credentials.
• A connection interceptor runs SET LOCAL request.tennant_id and request.user_id on open, which PostgreSQL row-level security policies can read.
• Outbound, InvokeHandlerMiddleware catches every exception, maps it to 400, 404 or 500 inside Response<T>, and logs the request and response pair to the API call log table.

Backend

Twenty projects, one request pipeline, and a database per county. The solution is cattax.sln on .NET 10: EF Core 10 with Npgsql, AutoMapper, FluentValidation, NLog, Quartz, Swashbuckle, the AWS S3 SDK, SSH.NET, FileHelpers, EPPlus, OpenXML, DinkToPdf and EFCore.BulkExtensions.

1. CTX.Services398 files44k
2. CTX.Entities450 entities, 168 SQL scripts17k
3. CTX.ImportExportFilesparsers, exporters, SFTP16k
4. Cattax (Web API host)95 controllers13k
5. CTX.Tests145 files, 517 tests12k
6. CTX.Calculationspenalty, interest, discount, bills8.5k
7. CTX.CartManagerCart.cs, Payments.cs4.8k
8. PciToCatalisMigrationlegacy ETL4.6k
9. CTX.RepositoriesGenericRepository<T>4.1k
10. BackgroundProcessorQuartz, 44 jobs3.1k
11. CTX.UnitOfWorkFactorylazy repositories2.9k
12. CTX.ReportCombit REST client1.1k
13. CTX.Configuration761
14. CTX.AWSS3377
15. CTX.IdentityServer317
16. CTX.Encryption268

1. GET284
2. POST149
3. PUT124
4. DELETE91
5. PATCH1

Schema as scripts

The DbContext is scaffolded, with no EF migrations. Every schema change ships as an ordered SQL script in the Entities project, and release folders hold the migration sequence for each tenant.

Services own their scope

A controller action creates its service with the caller's tenant and user, and disposes it at the end. Each service opens its own unit of work, so there is no shared DbContext between requests.

Global versus tenant

A separate non-tenant unit of work serves global tables: tenant master, process jobs, permissions and API call logs. Everything else is read through the tenant's own connection.

How the states differ

Almost entirely through data: per-tenant settings, process-job rows, item types and rate tables. The exceptions are deliberate modules: 32 FL SWA lookup controllers and the AG, CO, NAV and BUMP imports for Palm Beach; Patriot imports, privilege licences and a mobile-home penalty branch for Jackson County; three Virginia import jobs.

Background processor

A Quartz.NET console service with 44 job classes, deployed per environment and state on Windows EC2. On start it reads every enabled process-job row for every tenant, resolves the class by reflection and schedules its cron expression. Work arrives as process-queue rows written by the API; a base job claims the next row, heartbeats every ten minutes, marks it complete or complete-with-errors and emails on failure. Stuck rows reset on restart. Jobs cover appraiser, hauler, CO, bump and Patriot imports; bump, TRIM, bill-print, escrow and tax-sale exports; bill calculations; report rendering; bill PDFs; the SWA new-year roll; and bump rollback.

Calculations

Tiered penalty and interest rates with a cumulative cap and minimum amount; tiered discounts by effective date; bill-run to invoice; prorated mobile homes; privilege licences by month with sliding or flat rates; SWA non-government and government bills; and minimum payment, where any item under $100 is due in full.

Frontend

A React 19 portal with 127 routes, one auth singleton and six stores. Seventy feature folders in total; beyond the largest, most are reference-data maintenance screens (DOR codes, hauler codes, boundary codes, SWA class codes) sharing one table-and-drawer CRUD pattern.

1. ParcelRecord62 files31k
2. ParcelRecordVA66-file Virginia fork27k
3. Account7.9k
4. PrintFiles (receipts)11 templates7.5k
5. AddItem5.0k
6. CustomUI (table, tabs, top bar)4.2k
7. Home (search)4.1k
8. Cartthe cash register3.8k
9. Users3.3k
10. MillageRate3.2k
11. NAVFileData2.5k
12. MotorVehicle2.2k

Auth and token refresh

Login runs the authorization-code flow with oidc-client-ts. Between twenty minutes after sign-in and two minutes before expiry, each call exchanges the refresh token at /connect/token and writes the new token back to the store. An expired token logs the user out.

Tenancy in the UI

Tenancy is per user. The top bar offers "Change my tenant" from the user's linked tenants; a server call switches and the app reloads. Tenant and client-type settings gate menu items, item types and the appraiser link.

Accessibility baseline

626 aria attributes across 135 files, keyboard-enabled rows in search and the top bar, focus styles in the MUI overrides. The WAVE tickets I worked added most of the labels and names.

Known debt

Plain JSX without type checking, a near-copy ParcelRecordVA fork, i18n scaffolding with seven keys, no unit tests, no skip links. Listed because it shaped my decisions.

The screens that matter

Parcel Record is the product. Sixty-two files and 30,581 lines sit behind that one screen: invoice actions (void with reason, undelete with a required note), installment and split-bill panels, supplemental bill drawers for real estate, personal property and SWA, payment history, S3-backed document maintenance and the change log.

The cart is where the money moves. Cash over the total due opens a Change Due modal. Check over the total due offers a refund check or "keep in unallocated cash". Paying below the minimum needs a supervisor override. Receipts switch template by item type: real estate, personal property, mobile home, solid waste, government, privilege licence, aircraft, transient business.

Receipts render in the browser with @react-pdf/renderer: eleven templates chosen by item type, with the tenant's watermark and seal from the global store. Work orders export to PDF with html2pdf, the account page uses jsPDF with autotable, and bills are rendered server-side by DinkToPdf.

Screen by screen

Eighteen screens of the portal, redrawn in the product's own theme. These are faithful re-creations of the real layouts, not screenshots of customer data; every value shown is illustrative. Pick a screen, then hover, focus or tap a callout to light the part of the screen it explains.

Screen 3 of 18

Parcel record: invoices

Jump to a screen

123456

Full size

The hub for one account: header, tabs, invoices, summary and payment history.

The postmark date chip changes interest and discount; the tab set follows the item type; each invoice expands to its lines and line values; the row menu holds supplemental bills, chargebacks, bankruptcy, printing, removal and undelete; the payment history panel opens receipts and starts voids and reversals.

1. 1Postmark dateThe calculation date drives interest and discount on every amount shown; changing it asks for confirmation.
2. 2Account headerOwner, address, status chips sorted by severity, unallocated cash and the account tools. The tab set below changes with the item type.
3. 3Pay in full or minimumThe split button offers add to cart, pay in full, or pay the minimum (50%).
4. 4Row menuSupplemental bill, chargeback, bankruptcy, print invoice, remove a never-paid invoice, undelete with a note.
5. 5Expand an invoiceLines and line values underneath: tax, fees, installment and the dates each covers.
6. 6Payment historyEvery payment on the account with receipt, void and reverse actions.

Contributions

Every month since December 2024, in both repositories. Front end in the accent, back end in ink.

Commits authored per month

Month	Front end	Back end
Dec 24	3	12
Jan 25	0	0
Feb 25	3	2
Mar 25	4	6
Apr 25	6	5
May 25	4	2
Jun 25	1	5
Jul 25	6	9
Aug 25	2	2
Sep 25	12	4
Oct 25	4	0
Nov 25	3	0
Dec 25	5	1
Jan 26	9	2
Feb 26	9	2
Mar 26	10	6
Apr 26	12	2
May 26	5	3
Jun 26	8	4
Jul 26	6	11
Aug 26	12	8
Sep 26	9	6
Oct 26	7	7

Where the tickets went

1. Bugs, defects and hotfixes56
2. Work orders, service requests40
3. Payments, cart, installments38
4. Accessibility (WCAG / WAVE)34
5. Receipts and print files30
6. Imports, processes, exceptions16
7. Reports and SQL functions12

Files I touched most

Timeline

From lookup-table CRUD to the money paths.

Spotlights

Work Order module

Twelve tickets, from three new tables to an inspector's editable grid. The Palm Beach SWA sends inspectors to properties to verify what is being billed: how many units, what building use, which service area. Those visits had lived outside the tax system. The Work Order module puts the task, its notes, its status history, its attachments and the per-building findings on the parcel itself.

What I built

• Tables and services for TaskMaster, TaskNotes and TaskStatus: paged listing with include-disabled and hide-completed filters, notes and files CRUD, soft delete.
• New work-order fields, attachment validation, empty-state fixes (no more 12/31/1969 dates).
• Service Request tab (WO-01) and Service Request Area (M-1): back end and front end.
• Building Details grid (WO-02.4): add row as "Added by Inspector", inline edit, save or discard, status auto-populates on modified rows.
• Soft delete with a required reason (demolition, lot change, reclassification, duplicate, other with notes), undelete, and a show-deleted toggle; deleted rows keep who, when and why.
• Permission gating through the portal's permission context.

Decisions worth noting

• Status history is its own table rather than a column, so an auditor can see who changed what and when.
• Delete is a soft delete with a reason because inspectors' findings are evidence; nothing billed is ever lost.
• Row history is kept per building, with revert gated by its own permission and the current tax year.

Receipts you can trust

A receipt is a legal document. It must not change after it is printed. Jackson County went live on the cash register and QA found a family of defects that all came from one design flaw: receipts were rendered from the current state of the account, not from the state at the moment of payment. Pay the remaining balance of a partially paid invoice and the old receipt silently changed. Edit the payor and the receipt did not update. Pay in two steps and the invoice amount shown was wrong.

Try it. Post the second payment under each rendering and watch what receipt 1 says.

Snapshot at payment

The receipt now carries the invoice lines paid up to that payment and an InvoiceAmount captured when the tender posts, returned by the API and stored with the payment.

Single-invoice rule

The receipt uses the captured invoice amount as Total Due only for single-invoice receipts; multi-invoice receipts sum lines, and Total Due is clamped at zero.

Partial payloads preserve values

The update-details endpoint merges rather than overwrites, so editing a payor cannot blank other fields.

Template fixes

Paid-date timestamp, mailing address, ZIP field duplication, Owner Name 2 hidden when blank, across the real-estate, personal-property, mobile-home and general receipt templates.

• TCCT-3645Receipts should not adjust dynamically
• TCCT-3773Incorrect invoice amount after paying remaining balance
• TCCT-3839Invoice lines paid up to the payment on receipts (hotfix)
• TCCT-3315Edit payor does not save; receipt not updated
• TCCT-3507Paid date missing timestamp
• TCCT-3885ZIP field duplicated on refund receipt

Reports and imports

The two edges of the system where the mainframe era still lives.

In-House Account Balance Summary (IHSUMM). A finance report the SWA runs to reconcile receivables. Delivered as a PostgreSQL function, fn_ihsumm, registered in the report menu tables and rendered by the Combit report server. First version shipped June 2026 (TCCT-3281), then a defect pass (TCCT-3411). The August fix: interest from the paid section was not captured, so the INTEREST column read 0.00 and the total balance was understated (TCCT-3481). Total due now includes payment history.

Property Address Listing (report 129). A roll listing by property address. SQL function plus a report-number guard, CSV only, and the "All" filter requirement removed after customer feedback (TCCT-3295). Also CO report updates (TCCT-1764) and the DR-409A certificate.

-- fn_ihsumm.sql (excerpt) · Combit/FL/IHSUMM
CREATE OR REPLACE FUNCTION public.fn_ihsumm(p_tax_year integer)
RETURNS TABLE (pcn varchar, owner_name varchar,
               bill_amount numeric, interest numeric,
               payments numeric, balance numeric)
LANGUAGE plpgsql AS $BODY$
BEGIN
  RETURN QUERY
  -- IH bill-installment lines for the year
  WITH ih_line AS (
    SELECT ald."ArLKey", inv."ArVKey", inv."AcKey"
    FROM "ArInvoiceMaster" inv
    JOIN "ArLineData" ald ON ald."ArVKey" = inv."ArVKey"
    JOIN "BillInstallmentData" bid ON bid."BidKey" = ald."BidKey"
    WHERE inv."ArVBillYear" = p_tax_year::SMALLINT
      AND bid."BsKey" = 'IH'
  ),
  -- line values, canonical type, IH payments …
END $BODY$;

Import Exception worker screen. Appraiser (NAV), hauler and CO files arrive as fixed-width or delimited text. Rows that fail validation used to stop the whole file. The exception screen, specified by the BA in Confluence and built by me on both sides, turns that into a workflow: six pluggable validation workers (account number, amount range, missing column, data type, required field, duplicate) tag each failing row with a reason.

Also on the file side: the NAV appraiser import (TCCT-394) with its header and detail tables and the process-queue model; boundary table rollover into the new year, parts 1 and 2 (TCCT-899); report queue time display and date format for the SWA (TCCT-3515); report 129 restricted to CSV and All Residential Collection Units (CIS-089) handed to Combit.

Accessibility

Government customers audit against ADA and WCAG 2.1 AA with the WAVE browser extension, and every error on a page is a finding. Over ten tickets I cleared the reports on the Home page and menus for both tenants, the Cart, the Parcel Record and its drawers, global search, and the user admin screens.

626

aria attributes in the portal today

13

WCAG tickets I closed

2

tenants audited page by page

1. Home and menus (2 tenants)5
2. Parcel Record and drawers4
3. Cart2
4. Global search1
5. Users and tenants1

• Form labels and aria-label on every input in the Edit Item Attributes and Update Item Details drawers (16 missing labels in one drawer alone).
• Empty buttons given accessible names; icon-only controls described.
• Checkbox and label association in tables; contrast fixed on status text.
• Landmarks and heading order on Home so screen readers can navigate.

Money rules

Mississippi lets a taxpayer pay a minimum amount on real estate, personal property and mobile home bills. The rule misbehaved when the amount due was under $100: the "minimum" exceeded the balance, and the cart flagged a legitimate tender as an overpayment.

• Backend: effective minimum becomes the balance when the balance is under $100, per item subtype (TCCT-2871).
• Frontend: cart mirrors the rule and the Minimum Payment button no longer flags overpayment when tender exceeds the minimum but not the total due (TCCT-2718, 2793, 3553).
• Follow-on in progress: underpayment over the threshold (TCCT-3968).

Other correctness work

• Voiding a reversal re-applies the original payment (TCCT-670).
• Discount removal and interest and penalty application on account and invoice (TCCT-1053).
• Interest and discount displayed for every item type on the Parcel Record (TCCT-2342).
• Implicit integer division corrected in a calculation path.
• Unallocated cash: ability to add to it from the register (TCCT-434).
• Initial installment creation for the SWA (TCCT-1006).

Delivery pipeline

Build once, promote the same image through four environments. Azure DevOps pipelines, AWS ECS, Terraform.

# Dockerfile, build stage
RUN jq 'to_entries | map({(.key): ("$"+.key)}) | from_entries' \
    src/config.json > src/config.tmp.json
RUN npm run build
# runtime stage: nginx:alpine, non-root, 8080
ENTRYPOINT ["start-nginx.sh"]   # envsubst at start

Runtime configuration without rebuilds

The React app imports a JSON config module at build time. The Dockerfile rewrites every value to a $KEY placeholder before vite build; at container start, start-nginx.sh runs envsubst over the bundled JS. The same image therefore serves dev, QA, stage and prod with different API hosts and OIDC clients.

Hardening in the edge container

HSTS with preload, nosniff, frame-ancestors same-origin, strict referrer policy. nginx runs as the nginx user with server tokens off and gzip on text assets. try_files $uri /index.html keeps deep links alive on refresh; /healthr answers the ECS target group.

Backend quality gate

xUnit v3, NSubstitute and EF Core InMemory: 517 tests in 145 files, fully offline. Tests exercise controller to service to unit of work to repository against an in-memory database, plus the fixed-width parsers. The dev pipeline runs the suite before the image is built; SonarQube runs it with coverage weekly on main. Swagger shows the connected database name so nobody tests against the wrong tenant (my TCCT-2642).

What Terraform provisions for the API

ECS task definition and service, security group, ALB target group and listener rule, CloudWatch log group and the IAM task role. Database credentials come from SSM parameters; state is remote; dev and prod have their own variable files. The API image is aspnet 10 on port 5211 with the Chicago time zone.

Background processor deploys separately

One Windows EC2 service per environment and state (FL, MS). A PowerShell script stops the process, unzips the build and copies everything except the environment's settings file. Restart is a deliberate manual step so an overnight import is never interrupted mid-file.

Reflection

What changed in how I work, after twenty-two months on the platform.

What I would do differently

• Snapshot receipts from day one. Every receipt defect traced back to rendering from live state; the fix was obvious in hindsight and expensive in sequence.
• Push for a Vitest suite in the front end. The backend has a real gate; the portal's only automated check is an AI review.
• Name fields once. Casing mismatches between DTOs and JSX (UsNumb, ArYTKey) cost real hours; a shared contract or TypeScript would have paid for itself.

What I learned

Own the whole slice.

The tickets I am proudest of touch a SQL function, a service, a controller, a store and a drawer. Being the one person across that path is why they shipped in one sprint.

Money logic belongs in one place.

Minimum payment lived in the cart and in the API; keeping them in step was the bug. The backend is now the source of truth and the UI mirrors it.

Accessibility is a checklist, not a vibe.

WAVE made it measurable, and measurable work gets finished.

Read the Confluence page first.

The exception-screen spec answered every edge case before I wrote a line.

239

commits by me, both repositories

135

pull requests merged

74

Jira tickets delivered

Feature catalogue

Part one told the story. This part is the reference: what each screen shows, which endpoints it calls, what rules the backend enforces, and where I worked on it. Facts were read from the code on 14 October 2026.

Stack

• .NET 10
• ASP.NET Core
• C#
• EF Core
• PostgreSQL
• React 19
• MUI v5
• Zustand
• xUnit v3
• Docker
• AWS ECS
• Terraform
• Azure DevOps
• WCAG 2.1 AA