Camilo Castro
All workCase 01 / 05

Sistema Contable + Nómina Client system

Payroll & accounting engine

The factory's own replacement for Siesa ERP: Colombian payroll, automatic accounting vouchers, DIAN electronic payroll and PILA social-security files — with snapshots, reversals and an audit trail.

  • Reverse-engineered Siesa's payroll documents and wrote down 22 business rules and 18 architecture decisions before the engine existed.
  • Every payroll run becomes balanced accounting vouchers, DIAN UBL XML signed with XAdES, PILA flat files and bank payment batches.
  • 569 automated tests — including a golden test that replays January 2026 end to end — behind a nine-stage CI pipeline.
Client
Industria Bizcopan Zapatoca — bread manufacturer, ~50 employees
Role
Sole developer: discovery, architecture, back end and front end
Year
2026 In build · go-live Jan 2027
Stack
  • Python
  • FastAPI
  • SQLAlchemy 2 (async)
  • PostgreSQL 16
  • Alembic
  • Redis + arq
  • React 18
  • TanStack Query
  • Tailwind CSS
  • pytest
  • GitHub Actions
  • Docker
Live draft of the first September fortnight in the ledger-style interface: section rail and tabs, eight employees with hours, earnings, deductions and net pay, one row expanded into its concept lines and the totals pinned at the bottom.
The home screen on a phone, in the dark theme: shortcuts to the day's tasks.

The brief

Bizcopan, a bread factory in Zapatoca (Santander), runs payroll and accounting for about fifty people on Siesa, a commercial ERP. The goal: replace it with a system the company owns, aligned with Colombian labor law and trusted by the accounting team from day one.

Trust is the hard part, so the project started without code: a study of the legal framework, reverse-engineering of Siesa's monthly documents, a questionnaire with the person who runs payroll, and a data model built from what the old system actually produces.

What I built

  • Payroll engine for fortnightly and monthly runs, with monthly snapshots of provisions and contributions
  • Novelties: overtime and surcharges, leave, sick leave, vacations and loan installments
  • Automatic accounting vouchers for every payroll, with reversals and a chart-of-accounts tree
  • DIAN electronic payroll: UBL XML, XAdES signature and transmission tracking
  • PILA flat files with integrity hash, payment batches and bank flat files
  • Employee inquiry by period, opening balances imported from Excel, month-end closing
  • A ledger-style interface in light and dark: section rail, tabs, grouped processes and a Ctrl K “Go to…” search

Architecture

  1. Employees & contractssalary · EPS · pension · ARL
  2. Noveltiesovertime · leave · loans
  3. Yearly parametersminimum wage · rates · thresholds
Payroll enginefortnight / month · 22 rules · monthly snapshots
  1. Accounting vouchersbalanced · reversible
  2. DIAN e-payrollUBL XML · XAdES signature
  3. PILA fileflat file · hash · status
  4. Payment batchesbank flat files

Every change passes

  1. 1ruff
  2. 2mypy --strict
  3. 3pytest unit
  4. 4pytest integration
  5. 5pytest golden
  6. 6alembic ↑↓
  7. 7front-end build
  8. 8docker build
  9. 9deploy staging

Under the hood

  1. Rules before code

    22 business rules and 18 ADRs were written and reviewed before the first migration. Each module's design names the rules it implements, so a disagreement about a number becomes a conversation about a rule.

  2. Tests that include the real world

    Unit tests for pure calculations, integration tests against a real PostgreSQL started with testcontainers, and a golden test that replays a full month of payroll.

  3. CI as a gate

    ruff, mypy --strict, three pytest suites, an Alembic upgrade/downgrade round-trip, the front-end build and a Docker build must pass before staging deploys.

  4. Safe to rehearse

    A playground mode mocks DIAN and the banks and shows a banner on every screen, so the accounting team can practice without anything leaving the building.

  5. Async where it pays

    SQLAlchemy 2 async on FastAPI for the API, Alembic kept synchronous by decision, and DIAN retries and polling in an arq worker on Redis with backoff.

Gallery

Home screen in the dark theme: shortcuts to the daily tasks and the seven steps of the month-end route, next to the keyboard shortcuts.
Home: shortcuts for the day and the month-end route, step by step.
The “Go to…” palette open over the home screen, listing screens that match the typed letters, each with its section.
Ctrl K: any screen by name or code, as accountants used to in Siesa.
Chart of accounts as an expandable tree: assets, liabilities, equity, income, expenses and production costs.
The company's chart of accounts as a navigable tree.
Yearly parameters for 2026: health, pension and severance percentages, transport allowance and thresholds.
Yearly legal parameters live in data, not in code.
Reports index in the dark theme, grouped into accounting, payroll, controls and reconciliations, and contracts.
Reports grouped by what they answer: accounting, payroll, controls.
The vouchers generated by the payroll run on a tablet, one open with equal debits and credits.
Every payroll run posts balanced vouchers.
The live payroll draft on a phone, in the dark theme, with the totals pinned at the bottom.
The live draft on a phone, totals always in view.
Dialog to add a novelty to an employee: earnings and deductions tabs, and for overtime the hours, the ordinary hourly rate filled automatically, the surcharge factor and the cost center.
Adding overtime: the hourly rate fills itself in.

Where it stands

Payroll, accounting and social-security modules are built and tested. A parallel run against Siesa is planned for October–December 2026, with go-live in January 2027.

Multi-company support is in the design from the start — a second company is already on the roadmap.

Screens show fictional employees created in the system's playground mode. No real payroll data appears on this site.