5.8 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.
================================================= Version: v0.3.0 Date: 2026-03-09
Major milestone release.
Core billing workflow now complete.
Working systems:
Invoices
Create / Edit / Lock after payment
Payments
Manual payments with invoice recalculation
Exports
CSV export Batch CSV export PDF export Batch PDF ZIP export JSON export
Printing
Single invoice print Batch invoice print
Reporting
Revenue report Printable report JSON report export Selectable report frequency
Configuration
Business identity Tax settings Logo support Report frequency selector
Deployment
Flask backend MariaDB database Lightweight container operation confirmed