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
- Gateway (Spring Cloud Gateway, WebFlux): single entry point, JWT validation against Keycloak, and licence checks per module with a short cache.
- Invoice: documents, numbering, status transitions, recurrence, purchases, imports, reports, PDFs and attachments in GridFS.
- User: tenants, profiles, regional and invoice preferences, dashboard 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 a tenant may use, issued as signed entitlement tokens.
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.
- Each hour at the rate of its day. Rates are effective-dated on the project or the client's contract. A rate change entered on 15 October with effect from 1 October re-prices unbilled time, and shows exactly which already-issued invoices it would have affected, without rewriting them.
- Contracts set the terms. A client can have one contract in force on any day, with a lifecycle (draft, active, expired, terminated), amendments and extensions, minimum and maximum hours or value, and reminders before notice deadlines.
- Billing rules split the hours. A client's billable time can stay on the project it was logged on, or be split by ratio or evenly across the projects that ran in the period. The invoice keeps the allocation it was created with.
- Fixed fees are billed once. A fixed-fee project's time is still tracked for reporting, but one invoice line bills the agreed amount, never the hours. Amendments, credit notes and explicit returns to billable all keep the fee from being billed twice or lost.
- Checks before generating. Right before an invoice is generated or issued, Doktally looks for problems that would make it wrong (missing rate, contract not in force, currency mismatch, a fee held by another draft). Errors stop it; warnings can be accepted.
- Every line explains itself. "How this line was calculated" shows hours × rate = amount, the rule and the contract behind the rate, and every time entry, day by day. A manual change is stored as an adjustment with a reason, next to the calculated amount.
- Time is locked once billed. A time entry can be on only one invoice. A draft reserves its time, an issued invoice locks it, and cancelling or crediting an invoice does not free the time unless someone returns it to billable explicitly.
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
- Bank statements with reasons. CAMT.053, MT940 or the bank's CSV are imported once, payments are matched to invoices by the reference, the amount still owed and the payer, every proposal says why, and each month's closing balance is checked against the books. A difference means a missing statement.
- The euro changeover. An account converted from leva keeps its earlier months in leva, VAT ledgers before 2026 are converted on import, and leva and euro are matched at the fixed rate 1.95583.
- Retainers and recurring charges. A monthly fee with included hours, rollover up to a cap and excess hours at the rate of their day; fixed charges such as hosting billed every period, each occurrence exactly once.
- Supplier subscriptions. What the business pays every month or year, renewals and cancel-by dates, and a reminder when a supplier invoice that should have arrived is still missing.
- A secure invoice link. The client opens the invoice without an account, downloads it, and acknowledges or disputes it with a comment; a dispute arrives as an action, and the invoice's legal status does not change.
- A month-close checklist. Billable time not invoiced, overdue invoices, disputes, contract notice deadlines and recurring documents that failed, each closing itself when dealt with.
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
- direct submission of declarations 1 and 6 to НАП through its API, once signing with a qualified electronic signature works from the server
- asymmetric (RS256 / JWKS) entitlement tokens, and billing and a self-service portal for licences
- usage metering per organization
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
- VAT ledgers straight from the files sent to the tax office
- Invoices that can explain every amount
- The euro changeover without the mess
- Payments matched with a reason, and a balance that must agree
- Never forget a supplier invoice again
- Contracts that remember every change
- Retainers with included hours, rollover and a cap
- A month-close checklist that finds the money you forgot
- Your data is yours to take
- Business trips reported and rebilled in one go