3.9 KiB
OTB Billing – Project State
Version: v0.3-dev
Status: Active Development
Backend: Flask (Python)
Database: MariaDB
Default Port: 5050
Install Location: ~/otb_billing
Overview
OTB Billing is a lightweight contractor-focused billing system designed to be:
- self-hostable
- deployable via installer
- database-driven
- portable across Linux servers
- simple HTML frontend with strong backend logic
The system is intended to support both:
- client self-hosting installs
- managed hosted deployments under outsidethebox.top
Current Core Features
Client Management
- create/edit clients
- client code system
- client contact details
- client ledger link
Services
- service code system
- service descriptions
- reusable services for invoices
Invoices
- automatic invoice numbering (INV-####)
- invoice creation
- invoice editing
- invoice locking when payments exist
- issued / due dates
- invoice status system
Statuses:
- draft
- pending
- partial
- paid
- overdue
- cancelled
Payments
- record payments
- payment confirmation
- payment reversal
- invoice payment tracking
- remaining balance calculation
Ledger
- client credit ledger
- positive / zero / negative balance color indicators
- manual credit entries
Invoice Rendering
- HTML invoice view
- printer friendly layout
- invoice totals / remaining balance display
- payment status badges
PDF Invoices
- PDF generation via ReportLab
- downloadable invoices
- branded invoice header
- tax number support
- payment terms and footer support
Settings / Configuration System
Database-stored settings accessible at:
/settings
Configurable fields:
Business Identity
- business name
- slogan / tagline
- business email
- business phone
- business address
- website
- business registration number
Tax Settings
- tax label
- tax rate
- tax number
- local country
- apply tax only to local clients
Invoice Behavior
- invoice footer
- payment terms
- default currency
SMTP / Email (prepared for future email invoices)
- SMTP host
- SMTP port
- SMTP username
- SMTP password
- from email
- from name
- TLS / SSL flags
Architecture
Backend: Flask
Database: MariaDB using mysql-connector-python
PDF Engine: ReportLab
Dependencies defined in:
requirements.txt
Flask template system used for UI.
Installer Philosophy
OTB Billing is designed to support automated installs.
Target workflow:
fresh server → run installer → install python dependencies → install MariaDB → create schema → launch application
The goal is a single guided install path so non-expert Linux users can deploy it.
README.md will include:
- config file explanation
- installer instructions
- deployment examples
Security Considerations
Advanced settings such as database credentials should remain outside the main UI and be configured through installer or config file.
SMTP credentials are stored in the settings table but are not yet used for sending email.
Planned Features
Near Term
Email invoices
- attach generated PDF
- send via configured SMTP
Invoice defaults
- default currency
- default tax rules
Business branding
- configurable business logo
- invoice header logo
Reports
- outstanding invoices
- revenue summaries
- client account statements
Medium Term
Quotes / estimates Recurring invoices Invoice reminders Client portal
Long Term
Multi-currency handling Exchange rate support Accounting export (CSV / QuickBooks style) API access User authentication system Role permissions
Deployment Goals
OTB Billing should support:
Self-host installs
Managed hosting deployments
Multi-client environments
Target integration with:
outsidethebox.top hosting services.
Repository Discipline
Every version bump must:
- update PROJECT_STATE.md
- update README.md changelog
- produce full version snapshot ZIP backup
Example:
otb_billing-v0.3.0.zip
This ensures reliable rollback and historical tracking.
End of file.