InstalDesk

Quoting and VAT-invoicing SaaS for Polish installation contractors. Live at instaldesk.pl since April 2026, currently v1.9.0.

This repository is a write-up, not the code. InstalDesk is a commercial product and its source is closed. This page exists so the architecture is readable without a demo account.

---

What it is

Plumbers, electricians and HVAC technicians in Poland quote on site and invoice from the office, usually in a spreadsheet and a separate accounting program. From January 2027 the smallest Polish businesses also have to file every invoice through KSeF, the national e-invoicing system run by the Ministry of Finance.

InstalDesk does both halves: build a quote at the customer's flat, turn the accepted quote into a VAT invoice, and file it to KSeF without leaving the app. One subscription covers a web PWA and a Windows desktop client on the same account.

I built the product and I run it — including support and user contact.

Why KSeF is the interesting part

Most Polish invoicing tools reach KSeF through a third-party integrator. InstalDesk talks to the Ministry of Finance directly, which meant implementing the parts an integrator would normally hide:

• API v2 against the FA(3) XML schema — invoice serialisation, session handling, status polling, and the UPO (official confirmation) retrieval that proves an invoice was accepted.
• Two authentication paths for two clients. The web app authenticates with a KSeF token. The desktop client signs with a qualified certificate using XAdES-BES, which means building and signing the XML document locally rather than shipping the certificate anywhere.
• Failure handling as a first-class case. KSeF sessions expire, the gateway rejects malformed documents with schema-level errors, and a contractor on a building site is frequently offline. An invoice that cannot be filed right now has to stay valid and queued, not be lost.

Architecture

  Web PWA  ──┐                          ┌── PostgreSQL (cloud, per-tenant)
             ├── FastAPI (Python) ──────┤
Windows app ─┘         │                └── KSeF API v2 · Ministry of Finance
     │                 │
  SQLite (local)    Stripe
  offline-first     billing

• Offline-first on the desktop. The Windows client keeps a local SQLite database so quoting keeps working with no connection, and reconciles when it is back. The cloud copy is PostgreSQL.
• One account, two clients. The web PWA and the desktop app are the same tenant, not two products.
• Per-tenant isolation throughout, with KSeF tokens encrypted at rest.

Stack

Layer	Choice
Backend	Python, FastAPI
Data	PostgreSQL (cloud), SQLite (desktop, offline)
Clients	Web PWA, Windows desktop
Payments	Stripe — card, BLIK, Przelewy24
Integrations	KSeF API v2 (FA(3), XAdES-BES)

Around the core: subscription and renewal flows, a 14-day trial that does not ask for a card, transactional email, PDF generation for quotes and invoices, and XLSX/CSV import and export so a contractor can bring an existing price list in.

Status

Live since April 2026 and in active use by pilot users. Billing is wired and working, but there are no paying customers yet — the pilot runs on free accounts while the product is finished ahead of the January 2027 KSeF deadline for the smallest businesses.

Elsewhere

• Product: instaldesk.pl
• Author: Jakub Kierznowski · portfolio · LinkedIn