Doktally — Invoicing, time billing and VAT for small businesses

Summary

Doktally is my own SaaS for time tracking, contracts, billing, invoicing, bank statements and VAT. It is split into six Spring Boot services behind Spring Cloud Gateway, with Keycloak for identity, RabbitMQ for background work and an Angular client. Its core is a billing engine that can explain every amount it produces, and it handles the Bulgarian specifics (НАП ledgers, VIES, BNB data, the euro changeover) that general tools skip.

Subtitle

A multi-tenant invoicing and VAT platform for small Bulgarian companies, built and run by one person.

Domain

Invoicing / VAT / Small business

Target users

Freelancers, sole traders and small companies in Bulgaria, and the accountants who work with them.

Role

Founder / Product Engineer

Challenge

Issuing an invoice is the easy part. Before it come the questions that make it right or wrong: which hours are billable, at which rate on the day they were worked, under which contract, split across which projects, and whether any of them were already billed. After it come payments, credit notes, reminders, purchases, VAT ledgers for НАП, and the question of what the business actually earned this quarter. Small companies end up answering these across several tools and spreadsheets, and mistakes surface months later.

What I owned

Product decisions and the phased plan, service design, backend and frontend implementation, integrations with НАП files, VIES, BNB, banks and Keycloak, the release process, CI, Docker deployment, backups and monitoring.

Approach

Split by business area into services, keep identity and licensing at the edge, and move slow work (PDFs, emails, exports) onto RabbitMQ. Inside the billing engine, treat money as BigDecimal, keep calculated values apart from human adjustments, freeze what was issued, and make every number explainable from its sources.

Outcomes

I started Doktally in March 2024 to run my own company's paperwork, and it grew into a full product. Version 1.0 (spring 2026) covered documents, purchases, VAT imports, time tracking, dashboards, notifications and licensing.

Phase 1 since then turned it into a billing tool for contractors in general: contracts with effective-dated terms and a change log, fixed fees, retainers with included hours, recurring charges, billing-correctness safeguards, per-language documents, numbering per legal entity, data export, bank-statement matching and a secure invoice link the client can acknowledge or dispute. Several companies (tenants) run in one installation, each with its own users, roles, numbering and licence.

It is a one-person project: I decide what goes in, design the services, write the Java and Angular code, and run the production stack.

Details

Overview

I started Doktally in March 2024 to run my own company's paperwork, and it grew into a full product. It handles invoices and other documents, purchases, VAT ledgers, time tracking, a calendar of due dates, dashboards and notifications, for several companies (tenants) in one installation.

It is a one-person project: I decide what goes in, design the services, write the Java and Angular code, and run the production stack.


Architecture

Gateway (Spring Cloud Gateway, WebFlux): single entry point, JWT validation against Keycloak, identity headers re-derived at the edge, licence checks per module and feature with a short cache, and timeouts and circuit breakers per route.

Invoice: clients, projects, contracts, time entries, billing rules and schedules, fixed fees, documents, numbering, status transitions, payments, purchases, imports, reports, PDFs and attachments in GridFS.

User: organizations, members and roles, profiles, regional and invoice preferences, dashboards and column settings.

Catalog: items and services, following SAF-T conventions.

Notification: email templates, in-app and calendar notifications, fed through RabbitMQ.

Licensing: which modules and features a tenant may use, issued as signed entitlement tokens, managed from a separate License manager area.

Everything runs on Java 25 and Spring Boot 4 with MongoDB. The Angular client uses PrimeNG and ECharts.

flowchart TD
    W[Angular 22 + PrimeNG client] --> G[Spring Cloud Gateway]
    G --> KC[Keycloak]
    G --> LIC[Licensing service]
    G --> INV[Invoice service]
    G --> USR[User service]
    G --> CAT[Catalog service]
    G --> NOT[Notification service]

    INV --> MQ[RabbitMQ]
    MQ --> NOT
    NOT --> MAIL[Email / in-app / WebSocket]

    INV --> DB[(MongoDB + GridFS)]
    USR --> DB
    CAT --> DB
    LIC --> DB

Everything runs on Java 25 and Spring Boot 4 with MongoDB. The Angular client uses PrimeNG and ECharts.


Sending an invoice

sequenceDiagram
    participant U as User
    participant UI as Angular client
    participant GW as Gateway
    participant INV as Invoice service
    participant MQ as RabbitMQ
    participant N as Notification service

    U->>UI: Send invoice
    UI->>GW: POST send request (JWT)
    GW->>GW: Check licence for module
    GW->>INV: Forward request
    INV->>INV: Generate PDF, store in GridFS
    INV->>MQ: Publish send event
    INV-->>UI: Accepted (status: sending)
    MQ->>N: Deliver event
    N->>N: Render template, send email
    N-->>INV: Delivery status
    INV->>INV: Status transition + history entry
    N-->>U: In-app notification

The request returns as soon as the work is queued. PDF generation and email sending happen in the background, and the document's status and history update when the result comes back. Messages go through an outbox with publisher confirms, consumers are idempotent, and failed deliveries land in dead-letter queues instead of disappearing. The document also records who it was sent to, how and when, so later changes to the client's contacts never rewrite that history.


From hours to an invoice that explains itself

Most of the recent work is in the billing engine, because that is where small mistakes cost real money.

The Bulgarian part

General invoicing tools do not know about the files Bulgarian companies exchange with the Revenue Agency. Doktally imports the sales and purchase ledgers, VAT declarations and VIES reports submitted to НАП, removes duplicates by a business key, and turns them into a BG VAT report with filing checks: net VAT position, output VAT against input credit per period, purchase and sales journals. VAT numbers are checked in VIES, Bulgarian banks are recognised from the IBAN, and exchange rates come from the Bulgarian National Bank. Invoices, credit and debit notes and their emails can be produced in the client's document language.


Since version 1.0: money in, money out

Each of these is described with screenshots on its own page: Doktally use cases.


Decisions that mattered

Money is BigDecimal, everywhere. Early import keys used Double; they were migrated to BigDecimal along with the rest of the financial model. Multi-currency amounts are converted explicitly and shown per currency.

Calculated and adjusted amounts stay apart. A generated line keeps what the time and rate say it should be. A person's change is a separate adjustment with a reason, so the two can always be compared and rebuilt.

Issued means frozen. Issuing an invoice snapshots the client, items, VAT and the explanation of every line. Renaming the client, changing a rate or amending a contract later never changes what was sent; the app shows what changed since and suggests a credit or debit note.

Documents have a state machine and a history. Status transitions are explicit and configurable, and every change (fields, lines, attachments, payments, returns to billable) is recorded with old and new values. Users can add notes to history rows, which helps when an accountant asks why something changed.

Regression suites for the money paths. Every billing-critical scenario has its own end-to-end test on a small dataset, tagged so the whole billing and contract suite runs with one command. The demo dataset is itself checked to generate and issue its invoices cleanly.

Slow work goes through the queue. PDFs, emails and exports never block a request. The user gets a notification when the file is ready.

Tenant scoping in the repository layer. Lookups go through tenant-aware queries such as findByIdAndTenantId, so one company's data cannot leak into another's by a missing filter. Roles (owner, admin, accountant, user) are enforced in the API and reflected in the menu.

Licensing at the edge. The gateway decides which modules and features a tenant may call, so the business services stay free of licence checks. The gateway re-checks licences every 30 seconds, so suspending one takes effect almost at once.

Operable by one person. One Docker Compose file for production with Caddy for HTTPS, scripted MongoDB backups and restore, Prometheus metrics, and a switch that loads a complete demo. Every deployment is a release manifest of independently versioned services, each an immutable image built once.

Next steps

Technologies

Java 25, Spring Boot 4, Spring Cloud Gateway, Angular 22, PrimeNG, ECharts, MongoDB, RabbitMQ, Keycloak, Docker, Caddy, Prometheus

Engagement

PERSONAL_PRODUCT

Timeline

2024-03 – Present

Use cases