TicoConta

01

Context

A system I am building for my father’s business, to reduce the administrative load and make day-to-day work easier. It handles electronic invoicing under Costa Rican rules (working name: TicoConta) and includes timber volume and paper-invoice digitisation modules.

Responsibilities

• System design and architecture: a modular monolith with an import contract between modules
• Frontend development: an installable web app with React, TypeScript and Vite
• Backend development: a FastAPI API with deterministic tax calculation and document signing
• Data modelling and management in PostgreSQL 16 with Alembic migrations
• API design and implementation, including the integration with Hacienda’s public API
• Integration between the interface, the API, the database and external services
• Interface and user experience design for operating from a phone
• Testing, validation and technical maintenance with pytest, Vitest and Playwright

02

Problem

Go from evidence of a sale to a valid electronic invoice, and stop relying on notebooks and paper invoices to run the business.

03

Solution

A modular API that calculates taxes deterministically, generates and signs the XML documents, and an installable web app to operate from a phone. The timber and digitisation modules propose data that a person reviews before confirming.

Built

• Multi-company with configurable roles and chained audit logging
• Official catalogues (CABYS) and a deterministic tax calculator
• Invoice, ticket and credit/debit note XML validated against the official v4.4 schemas
• XAdES-EPES signing and immutable storage with SHA-256 verification
• Timber volume calculation with exact arithmetic and mandatory human review
• Invoice digitisation by project, with review, duplicate detection, an arithmetic check against the written total and PDF summaries
• Tax-authority (Hacienda) connector to submit documents and check their status, tested against a local simulator
• Working integration with Hacienda’s public API: taxpayer data lookup when setting up the business, implemented and verified

Planned, in progress

• Accounting system (next stage)
• Inventory module (in development, not yet committed to the repository)

04

Architecture

A modular FastAPI monolith on PostgreSQL 16 in Docker, with Alembic migrations, and a React, TypeScript and Vite interface. An import contract stops the AI modules from depending on the tax modules.

05

Technologies

• Python
• FastAPI
• PostgreSQL
• Alembic
• Docker
• OpenAI API
• React
• TypeScript
• Vite
• Tailwind CSS
• pytest
• Vitest
• Playwright
• Cloudflare Tunnel

06

Technical decisions

• Technical anti-production barrier: nothing is sent to the tax authority without explicit authorisation.
• Exact decimal arithmetic; the server always recalculates and the browser never sends computed amounts.
• Whatever the AI reads stays pending human review and never replaces the written total.
• Secret scanning on every commit, with sensitive files kept out of the repository.

07

Verifiable results

• According to the stage 2 closing report (29 September 2026): 556 backend tests passing with 94% coverage. They were not re-run in this review.

Known limits

• Looking up Hacienda’s public data is not issuing invoices: submitting documents and receiving their official acceptance have only been tested against a local simulator.
• In the repository, submitting documents to Hacienda’s production service is blocked in code until explicitly authorised.
• The repository’s data is fictitious.

08

Screenshots and evidence

Interface on desktop and mobile

Open full size ((opens in a new tab))

Open full size ((opens in a new tab))

Screen gallery

• Open full size ((opens in a new tab))

• Open full size ((opens in a new tab))

• Open full size ((opens in a new tab))

• Open full size ((opens in a new tab))

• Open full size ((opens in a new tab))

Real screenshots of TicoConta’s demo environment, with a fictitious taxpayer. Nothing was submitted to Hacienda and the account email is blurred.

Close

Documentation and tests

• Partial stage 2 closing report, logs and architecture decision record.