Inspiration
Recurring billing systems often break in quiet, costly ways when teams rush prototypes—like duplicate invoices on retries, rounding drift across totals and taxes, or lax record checks exposing another customer's data. We built sub_system to treat subscriptions, invoices, payments, and reporting as a strict, local-first workflow from the start so it can adapt cleanly across different domains.
What it does
Brightloop is a local-first subscription management and recurring billing platform that runs the full subscription lifecycle offline across a monorepo architecture:
- Catalog, Plans & Variants: Manages products, recurring plans, taxes, discounts, quotation templates, and product variants (including a +₹560.00 / 56000 paise variant add-on) using integer paise amounts.
- Subscription Lifecycle: Enforces state transitions across DRAFT, QUOTATION, CONFIRMED, ACTIVE, and CLOSED, along with pause/resume cycles (without mid-cycle proration) and draft renewals linked via renewedFromId.
- Billing & Payments: Runs scheduled node-cron billing and manual catch-up runs for ACTIVE subscriptions due on or before today, guarded by a unique constraint on subscriptionId and periodStart, payment balance limits, and cancellation blocks once any payment is recorded.
- Role-Based Portals & Reporting: Separates Admin, Staff, and Customer access with tenant-scoped customerId checks returning 404 on cross-tenant requests, paired with /api/reports/summary and /api/reports/overdue endpoints.
How we built it
We organized sub_system as an npm workspace monorepo with Docker support (docker-compose.yml for PostgreSQL 16 and Mailpit) across three packages:
- @brightloop/shared: Shared TypeScript types, Zod schemas, and INR currency/date formatters.
- Backend: An Express.js and TypeScript REST API using Prisma ORM and PostgreSQL 16, alongside a node-cron billing worker, pricing/discount utilities, reporting routes, tests, and scripts/benchmark.ts.
- Frontend: A React 18 and Vite web app styled with Tailwind CSS, using TanStack Query, React Hook Form, and Lucide Icons for role-based views and printable invoices.
Challenges we ran into
- Rounding & Discount Order: Using integer paise and tax basis points avoids floating-point drift, while applying product discounts before subscription discounts, splitting subscription discounts proportionally across lines with remainder handling on the last line, and calculating tax after discounts required careful ordering.
- Idempotency & Lifecycle Rules: Preventing duplicate period invoices across retries and state changes required a compound unique constraint on subscriptionId and periodStart, clearing nextInvoiceDate when closing, recalculating cycles cleanly on resume, and blocking overpayments or cancelling paid invoices.
- Tenant Isolation & Query Speed: Keeping customer queries scoped to token.customerId with 404 responses prevents ID enumeration, while summary and overdue reporting queries needed to stay fast as invoice volume grows.
Accomplishments that we're proud of
- Complete Local-First Monorepo: Built an offline-capable billing engine and role-based React UI tied together by shared Zod/TypeScript contracts and PostgreSQL constraints.
- Strict Billing Guardrails: Enforced integer paise pricing, deterministic discount allocation, payment caps, and duplicate-invoice protection at the service and database levels.
- Test & Benchmark Coverage: Added Vitest unit tests, integration test scripts, and benchmark tooling targeting sub-35ms p95 reporting over 20,000 invoices.
What we learned
Relying on UI checks alone is never enough when handling money and account boundaries; moving rules into shared schemas, database constraints, and deterministic helpers catches edge cases early and makes changes much safer when paired with automated tests and benchmarks.
What's next for Sub_system
- Domain Adaptation: Tailor products, plans, and workflows to fit the target domain while keeping the core state machine and billing invariants intact.
- Broader Edge-Case Testing: Expand test scenarios around renewals, partial payments, and larger dataset benchmarks.
- Workflow Polish: Improve reporting views, Mailpit/SMTP notification flows, and local setup ergonomics.
Built With
- docker
- express.js
- node.js
- npm
- postgresql
- react
- tailwind
- typescript
- vite
- zod