VOS: an Albanian fiscalization and accounting platform

The challenge: an invoice is not valid until the tax authority says so

Albanian law obliges every taxpayer to transmit each invoice to the tax authority at the moment it is issued. The invoice is not legally valid until the Central Invoice System returns its codes. In practice a business cannot simply print a receipt: it needs a qualified digital certificate, software that builds the exact XML the authority specifies, an XML digital signature, and a live connection, all within seconds of a customer paying. Every document type carries its own rules, cash registers have to be registered as devices and opened and closed daily, and when the connection drops invoices must still be issued and then reconciled inside a legal deadline. Separately, the books still have to be kept. The free government portal covers the minimum for the smallest taxpayers and leaves the accounting, the multi-business case and any integration with a business own systems unsolved. That gap is the product.

The specification VOS implements is the authority own, tracked through nine published revisions. VOS explains the process it automates at how fiscalization works in Albania.

• Real-time registration with the tax authority before an invoice is legally valid
• A qualified digital certificate per business, obtained, loaded and renewed
• Four distinct document types, each with its own schema and rules
• Cash registers registered as devices, opened and closed daily, with cash movements logged
• A legal deadline to reconcile invoices issued while the connection was down
• A technical specification the authority has revised nine times and counting

Our solution: seven surfaces, from the counter to the accountant ledger

VOS is one platform covering seven public hosts. The customer dashboard is where a business actually trades: a point-of-sale panel, a quick-invoice screen for counter speed, and full flows for each document type the law defines. Those are the fatura e thjeshtë, the simple invoice a consumer receives; the fatura elektronike, the electronic invoice exchanged between businesses; the fleta shoqëruese, the transport note that travels with goods; and self-billing. Alongside them sit cash register management, stock and warehousing, purchase handling and operator accounts. The accounting portal is the larger half and the part with the least competition in the Albanian market: the national chart of accounts in its seven statutory classes, a double-entry journal that will not post until it balances, monthly period locking, bank reconciliation with a CSV import wizard, the statutory purchase and sales registers, and a catalogue of 42 reports across 11 sections. An accountant works across every client from one place. Around those two sit an administration console, a documented REST API, a documentation site written in Albanian, a public no-signup demo, and a mobile app that adds biometric lock, push notifications and native camera scanning rather than reimplementing the interface.

The three fiscalized document types are set out at the VOS solutions page, and the accountant side at the accounting portal for accountants.

• Customer dashboard: point of sale, quick invoice, and a full flow per document type
• Fatura e thjeshtë, fatura elektronike, fleta shoqëruese and self-billing, each to its own schema
• Accounting portal: national chart of accounts, double-entry journal, period locking, reconciliation
• Statutory purchase and sales registers, plus 42 reports across 11 sections
• Administration console, REST API, Albanian documentation and a public demo
• Mobile app adding biometric lock, push notifications and camera scanning

Tech and architecture: how an invoice actually gets fiscalized

The stack is a Yarn workspaces monorepo on Turborepo: a Fastify and TypeScript API, PostgreSQL through Prisma with Redis for caching and rate limiting, Next.js and React web apps, a prerendered Vite marketing site, Docusaurus documentation, and an Expo mobile shell, deployed on k3s behind Traefik and Cloudflare. Fiscalizing one invoice runs six steps. The business PKCS#12 certificate is loaded and the tax identifier read from the certificate itself rather than trusted from user input. The internal invoice code is built from a canonical string of issuer, timestamp, invoice number, business unit, register code, software code and total, digested, signed with the business private key, and hashed; the code and its signature are returned from a single signing pass so the two can never drift apart. The request document is built to the authority schema, holding all money in hundredths of a lek so that net plus value added tax equals total exactly. The request is signed with an XML digital signature, exchanged with the Central Invoice System over mutual TLS, and the signed request and response are archived in their own table for the retention the law requires, apart from the invoice row so bulky payloads never weigh down ordinary queries. Fifteen distinct tax-authority operations are implemented across four separate government web services, and electronic invoices are additionally generated as UBL 2.1 against the European EN 16931 standard.

The integration surface is documented publicly, in Albanian, at the VOS documentation site.

• Fastify and TypeScript API, PostgreSQL via Prisma, Redis, Next.js and React, k3s
• Certificate loaded from PKCS#12, tax identifier read from the certificate, never from input
• Invoice code and its signature produced in one signing pass so they cannot diverge
• All money held in hundredths of a lek so the tax arithmetic reconciles exactly
• XML digital signature and mutual TLS to the Central Invoice System
• Fifteen tax-authority operations across four government web services

What we delivered: scope and depth, and a platform that is deployed

This is where a case study normally reports adoption. VOS has none to report yet, because commercial rollout has not begun, and we would rather say that than borrow a number. What can be measured is the scope and the state of the thing. The repository holds 312,209 lines of hand-written source across 1,970 files, with a further 238,707 lines of tests in 1,423 files; in the API, test lines almost exactly equal source lines. The API declares 647 endpoints of which about 607 are reachable. The data model runs to 98 models and 87 enums, with multi-tenancy structural rather than conventional: 69 models carry the business identifier directly, backed by 98 composite indexes. Across the platform there are 219 pages, being 127 application screens, 49 marketing pages and 43 documentation pages, all of the last in Albanian. It was built by three people over nine active months and 603 commits. All seven hosts are live and healthy, the application hosts correctly return noindex, and the legacy hosts from the previous brand redirect. Rollout is beginning.

The platform can be tried without a signup at the live VOS demo, and the product itself is at VOS, the fiscalization platform, which also publishes free tools including an Albanian value added tax calculator and an invoice verifier.

• 312,209 lines of hand-written source, plus 238,707 lines of tests
• About 607 reachable API endpoints of 647 declared, across 99 route files
• 98 data models and 87 enums, with tenancy enforced structurally by 98 composite indexes
• 219 pages: 127 application screens, 49 marketing pages, 43 documentation pages in Albanian
• 603 commits over nine active months, by three people
• Seven public hosts live and healthy; commercial rollout is beginning

What this case study says about working with Square

A regulated domain punishes the habits that pass elsewhere, so the interesting part of this project is not the feature list but how it was kept correct. Test-driven development is enforced by tooling rather than by policy: a hook blocks writing a new source file with no matching test, blocks on any lint error in the owning workspace, and blocks on a failing test run, and the house rules reject tests that assert nothing or that assert against a mock instead of a result. Every warning-level lint rule is promoted to an error; when linting was switched on for the backend the historical backlog of 10,635 violations was frozen into a baseline that may only shrink, and it now stands at 6,135, down 42 percent. Suppressing a rule needs a written reason and owner approval, and that requirement is itself machine-enforced. Done has a definition: affected packages pass lint, type check and tests, the change is deployed, the deployment reports healthy, the public URL returns 200, end-to-end tests pass, and someone has opened the page and looked at it. Roughly fifteen separate audits are recorded in the repository, covering security, legal compliance against the acts, accounting correctness, scale readiness and content. If you are buying software that has to be right rather than merely finished, that is the working method you are buying.

• Test-driven development enforced by a hook, not by policy: 15,418 tests across 1,401 files
• Every lint warning promoted to an error; the frozen backlog is down 42 percent and still falling
• Suppressing a rule requires a written reason and owner approval, machine-enforced
• A written definition of done that ends with a healthy deployment and a human looking at the page
• Roughly fifteen recorded audits: security, legal, accounting correctness, scale, content
• Correctness the domain forces: exact money arithmetic and tenancy enforced in code