Proxima Invoice
Proxima Invoice is an invoice management system built for ProximaOps. It replaces three n8n workflows (~1500 lines of JavaScript) that previously handled invoice generation, approval, and delivery for client service contracts.
What It Does
- Pre-generates invoices from Jira/Tempo time tracking data stored in ClickHouse
- Allows full manual editing before finalization — automated data is a starting point, not the final answer
- Generates branded PDF invoices using Go HTML templates and Gotenberg
- Manages approval workflows with status tracking and audit trails
- Syncs with PlanFact (accounting) and stores PDFs in Cloudflare R2
- Delivers invoices via Didox.uz (local) or email (international)
- Pricing calculator with margin analysis and quote generation
Why It Exists
The n8n workflows had several limitations:
- Hard to debug and maintain (~500 lines per workflow)
- No editing capability — invoices were fully automated
- No approval workflow — generated and sent directly
- No audit trail — no record of changes or decisions
- Difficult to extend for new deal types or business rules
Key Concepts
| Concept | Description |
|---|---|
| Application | A client service contract (from Jira/CDM) |
| Deal Type | SUP (support), HR (hourly), FP (fixed price) |
| Prefill | Auto-populate invoice from ClickHouse data |
| Finalize | Lock invoice and generate PDF |
| Status Machine | draft → needs_review → approved → sent → accepted → paid |
Architecture at a Glance
- PostgreSQL stores invoices (write database)
- ClickHouse provides worklogs and client data (read-only)
- Gotenberg converts HTML templates to PDF
- React frontend provides the user interface
Current Status
Phase 1 (Core Invoice Builder), Phase 2 (Approval Workflow), and Phase 3 (PlanFact + R2) are complete:
- Client list from ClickHouse
- 3-step invoice generator (select → edit → review)
- PDF generation via Gotenberg
- Invoice registry with filters
- Full editing with audit trail
- Approval workflow with status transitions and audit trail
- Telegram notifications on approval
- Cloudflare R2 PDF archival on approval
- PlanFact shipment sync on approval (with manual retry)
See Phase Roadmap for all 6 phases.
Next Steps
- Quick Start — Get the system running locally
- Project Structure — Understand the codebase layout
- Business Logic — How invoicing works
- API Reference — All REST endpoints