5.1 KiB
OTB Billing — Project State
Last Updated: 2026-03-09 Version: v0.3-dev Project Path: ~/otb_billing
Project Purpose
OTB Billing is a contractor-focused billing system designed to be:
- self-hosted
- portable
- database-backed
- deployable on fresh Linux systems
- suitable for managed hosting or client-installed deployments
The system is being built as a practical alternative to overly restrictive SaaS billing tools, with emphasis on ownership, simplicity, and contractor workflow.
Tagline direction:
By a contractor, for contractors
Current Stack
Backend: Flask
Database: MariaDB
PDF Engine: ReportLab
Primary Port: 5050
Dependencies file: requirements.txt
Deployment Philosophy
OTB Billing must remain a deployable product, not just a dev-only app.
Target install model:
fresh server → installer runs → dependencies install → MariaDB setup → schema setup → app launches
This remains a core project rule.
Current Core Features
Clients
- create client
- edit client
- list clients
- status field
- client code support
Services
- create service
- edit service
- list services
- service code support
- service status support
Invoices
- create invoice
- edit invoice
- list invoices
- automatic invoice numbering
- invoice print view
- invoice PDF download
- invoice lock after payment activity
- invoice statuses
Current invoice statuses:
- draft
- pending
- partial
- paid
- overdue
- cancelled
Payments
- record payment
- edit payment
- list payments
- overpayment guard on new payment
- overpayment guard on payment edit
- payment status display
- payment void / reversal workflow
- invoice recalculation after payment changes
Current payment statuses:
- confirmed
- reversed
Credit Ledger
- client credit ledger
- manual credit entries
- client balance color coding
- ledger link visible from client list/edit pages
Invoice Rendering
- HTML invoice view
- print-friendly layout
- PDF invoice generation
- client details on invoice
- status badge on invoice
- totals, paid, remaining display
Current Settings / Config System
Accessible from:
/settings
Stored in database table:
app_settings
Business Identity Settings
- business name
- business tagline
- business email
- business phone
- business address
- business website
- business registration number
Tax Settings
- tax label
- tax rate
- tax number
- local country
- apply local tax only flag
Invoice Behavior Settings
- default currency
- invoice footer
- payment terms
SMTP / Email Settings
- SMTP host
- SMTP port
- SMTP username
- SMTP password
- SMTP from email
- SMTP from name
- TLS flag
- SSL flag
Email sending is not yet wired, but config storage is now in place.
Current Known Good State
Confirmed working:
- dashboard
- clients
- services
- invoice creation
- auto invoice numbering
- invoice view
- invoice PDF generation
- payment entry
- payment overpayment prevention
- payment reversal / void
- payments list with invoice status and remaining balance
- settings/config page
- business identity shown on invoice view/PDF
Requirements
Current requirements.txt should include:
- Flask
- mysql-connector-python
- reportlab
- python-dateutil
- pytz
This file must remain complete so installer-driven deployment works in one shot.
Business / Product Direction
This system is intended to grow into a deployable billing product for small contractors and related service businesses.
Target strengths versus typical SaaS billing tools:
- simpler workflow
- data ownership
- exportability
- portability
- contractor-first design
- no hostage-style software design
Long-term success goal: build something users are happy to use and proud to own.
Planned Next Features
Near-Term
- email invoice sending using stored SMTP settings
- branding/logo support
- invoice defaults from settings
- improved tax application logic
- reports/export tools
- batch invoice export / print
Medium-Term
- quote / estimate system
- recurring invoices
- reminder workflows
- improved branding/theme polish
- better installer/update flow
Long-Term
- client portal
- role-based access
- accountant/export workflows
- job-tracking integration with related contractor platform modules
Advanced Settings Direction
Business identity and SMTP belong in settings UI.
Database credentials should remain installer/config-file driven, not casually editable in standard UI.
If advanced connection settings are ever exposed in UI, they must be clearly marked as dangerous / advanced and should avoid redisplaying stored passwords.
Repository Discipline
For this project going forward:
- keep PROJECT_STATE.md updated
- update README.md with version/build notes
- keep requirements.txt complete
- make full ZIP backup on version bumps
- push milestones to git
Example future archive naming:
otb_billing-v0.3.0.zip
Restart / Run Notes
Development run method:
cd ~/otb_billing python3 backend/app.py
During active development, run in a visible terminal so logs stay visible.
Do not rely on hidden/background launch during normal debug workflow.