SaaS Billing & Proposal Engine
A serverless proposal-to-invoice automation engine with approval-gated workflows, Albanian VAT compliance, and edge-native PDF generation.
This system was developed to replace manual proposal creation and invoice tracking across Albanian creative and technology studios. It introduces a structured approval-gated workflow — from proposal draft through client approval, contract execution, and automated invoice generation. The engine is deployed as a composable service layer, consumed by the institutional portal, and designed for reuse across multiple client organisations on shared infrastructure.
Proposal management in Albanian agencies was entirely manual: Word documents sent by email, acceptance confirmed verbally or by reply email, invoice amounts calculated by hand, and VAT applied inconsistently. There was no version history, no approval audit trail, no automated conversion from approved proposal to invoice, and no fiscal compliance mechanism. The result was frequent billing errors, delayed payments, and no structured data for financial analysis.
Cloudflare Workers were chosen over a traditional server because the proposal and billing workflows are event-driven and burst-patterned — not continuously loaded. A persistent server would be wasteful and introduce cold-start risk. The state machine approach (draft → submitted → approved → invoiced → paid) is enforced at the database layer using PostgreSQL enum types, not application logic, making it impossible to create invalid state transitions through API calls. PDF generation runs server-side to ensure consistent output independent of client browser capabilities.
System Layers
- Proposal draft, edit, and versioned submission
- Approval-gated state machine (draft → submitted → approved → contracted)
- Automated proposal-to-invoice conversion on approval
- Albanian VAT computation and fiscal line item validation
- Server-side PDF generation with branded template
- PDF delivery and Cloudflare R2 storage
- Invoice status lifecycle: open → paid → void → uncollectible
- Approval audit log with actor and timestamp
- Multi-currency line item support
- Role-gated access: only managers can approve proposals
Proposals and invoices are stored in separate normalised tables with a foreign key relationship. Proposal line items are a child table with quantity, unit price, VAT rate, and computed total — computed totals are calculated at query time via a database view, not stored, to prevent stale data. Status columns use PostgreSQL enums (proposal_status, invoice_status) with strict valid transitions enforced via database check constraints. Every status change is written to an immutable audit log table with actor ID, old status, new status, and timestamp.
The proposal editor follows a structured form layout — section by section — to enforce completeness before submission. Required fields are validated client-side with immediate feedback and server-side with structured error responses. The approval workflow surfaces as a single prominent action available only to users with the manager role. Invoice management presents outstanding, paid, and voided invoices in separate visual sections to reduce cognitive load. PDF preview is available before generation. All destructive actions (void invoice, reject proposal) require a confirmation step.
JWT tokens from Supabase Auth are validated on every Worker request — no trust is extended to the frontend. The proposals Worker verifies that the requesting user belongs to the organisation that owns the proposal before any read or write operation. Approval actions are double-gated: role check at the API and database-level check constraint on status transitions. Generated PDFs are stored in private Cloudflare R2 buckets — access is via signed URLs with a 1-hour expiry, not public file paths.
Worker cold starts are minimal — Cloudflare Workers use V8 isolates, not containers, so startup time is measured in microseconds. Database queries on the proposals table use a composite index on (organization_id, status) to serve the most common listing pattern efficiently. PDF generation is asynchronous — the Worker triggers generation and returns immediately; the client polls for completion. Large proposal histories are paginated server-side with cursor-based pagination to prevent unbounded result sets.
The proposal-to-invoice cycle that previously required multiple manual steps across email, spreadsheet, and accounting software is now a structured, auditable, single-platform workflow. Proposal approval is tracked with a complete actor log. Invoices are generated automatically on approval with correct VAT computation. The engine is deployed across two institutional client accounts and handles active billing operations.
Planned extensions include direct integration with Albanian fiscal authority APIs for e-invoice compliance (e-Fatura), electronic signature via a certified Albanian provider, automated payment reconciliation against bank statement imports, and a client-facing proposal acceptance portal that removes the need for email-based approval flows.
Build similar infrastructure for your organisation.