Local-First Payroll & Resident Tax Automation

Inspiration

Japanese small businesses often receive resident tax notices as PDFs or scanned documents. Payroll staff must manually read annual tax amounts, break them down by month, match them to each employee, and then enter them into payroll calculations. This process is time-consuming and prone to human error.

I wanted to build a practical tool that connects these fragmented back-office tasks while keeping sensitive payroll data on the local PC.

What it does

This application:

Imports Japanese resident tax notices in PDF, JPG, JPEG, or PNG format
Extracts text directly from PDFs when possible
Uses OCR as a fallback for scanned documents
Separates multi-employee notices into individual employee records
Extracts annual and monthly resident tax amounts
Lets a human review and correct the results before confirmation
Stores revision history and identifies the currently valid notice
Links confirmed monthly tax amounts to payroll calculations
Generates payslip PDFs and accounting CSV files from saved payroll records
Processes sensitive employee data locally without sending it to the cloud

How I built it

The application was built as a local Windows business application using:

Python
Streamlit
SQLite
ReportLab
Tesseract OCR
pypdfium2
pypdf
Pillow

Codex was used throughout development to implement, review, test, and improve the application. I defined the business rules, payroll workflows, data validation requirements, privacy requirements, and acceptance tests based on real small-business payroll operations.

Challenges

The main challenges were:

Correctly reading Japanese tax notices with different layouts
Supporting both text-based PDFs and scanned documents
Separating multiple employees from one municipal notice
Preserving employee codes with leading zeros
Preventing duplicate or incorrect payroll linkage
Making sure tax data is not applied before human confirmation
Packaging OCR dependencies so the application works on another Windows PC without global installation
Protecting existing payroll history during database migration

Accomplishments

I am especially proud that the application can take one multi-employee resident tax notice, create separate records for each employee, extract twelve months of tax amounts, allow human verification, and then automatically reflect the confirmed amount in payroll calculations.

The system also keeps the processing local, which is important for protecting payroll and personal data.

What I learned

I learned that AI-assisted development is most effective when domain rules, validation conditions, and test criteria are clearly defined by the business user.

Codex accelerated implementation, but accurate payroll software still required careful human decisions about tax workflows, employee data, revision handling, and operational safety.