You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
326 lines
6.1 KiB
326 lines
6.1 KiB
# OTB Billing — Project State |
|
|
|
Last Updated: 2026-03-09 |
|
Version: v0.3.1 |
|
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 |
|
- invoice email sending with PDF attachment |
|
- latest invoice email activity display |
|
|
|
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 |
|
- branding/logo support on HTML and PDF |
|
|
|
## Exports |
|
- clients CSV export |
|
- invoices CSV export |
|
- payments CSV export |
|
- filtered invoice CSV export |
|
- filtered invoice PDF ZIP export |
|
- monthly/quarterly/yearly accounting package ZIP export |
|
- revenue report JSON export |
|
|
|
## Batch / Print |
|
- filtered batch invoice print page |
|
- print-friendly revenue report |
|
|
|
## Reports |
|
- revenue report |
|
- report frequency selector |
|
- JSON report export |
|
- email revenue report JSON |
|
|
|
## Settings / Configuration System |
|
Accessible from: |
|
/settings |
|
|
|
Stored in database table: |
|
app_settings |
|
|
|
### Business Identity Settings |
|
- business name |
|
- business tagline |
|
- business logo URL |
|
- 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 |
|
- report frequency |
|
|
|
### SMTP / Email Settings |
|
- SMTP host |
|
- SMTP port |
|
- SMTP username |
|
- SMTP password |
|
- SMTP from email |
|
- SMTP from name |
|
- TLS flag |
|
- SSL flag |
|
- report delivery email |
|
|
|
## Email Logging |
|
Stored in: |
|
email_log |
|
|
|
Tracks: |
|
- email_type |
|
- invoice_id |
|
- recipient_email |
|
- subject |
|
- status |
|
- error_message |
|
- sent_at |
|
|
|
Currently logs: |
|
- invoice email sends |
|
- revenue report email sends |
|
- accounting package email sends |
|
|
|
--- |
|
|
|
# Current Known Good State |
|
|
|
Confirmed working: |
|
- dashboard |
|
- clients |
|
- services |
|
- invoice creation |
|
- auto invoice numbering |
|
- invoice view |
|
- invoice PDF generation |
|
- invoice email with PDF attachment |
|
- invoice email log display |
|
- 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 |
|
- logo display in HTML and PDF |
|
- clients/invoices/payments CSV export |
|
- filtered invoice export |
|
- filtered invoice PDF ZIP export |
|
- batch invoice print |
|
- revenue report |
|
- revenue report JSON export |
|
- revenue report email |
|
- accounting package ZIP export |
|
- accounting package email |
|
|
|
--- |
|
|
|
# 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 |
|
- invoice defaults from settings |
|
- improved tax application logic |
|
- accountant package scheduling / reminders |
|
- client account statement export |
|
- backup/install polish |
|
|
|
## Medium-Term |
|
- quote / estimate system |
|
- recurring invoices |
|
- reminder workflows |
|
- better installer/update flow |
|
- email resend history view |
|
|
|
## 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.1.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.
|
|
|