# 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 restrictive SaaS billing tools, with emphasis on ownership, simplicity, portability, and contractor/operator 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 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 - 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 Delivery - invoice email with PDF attachment - revenue report JSON email - accounting package 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 - 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 - email audit logging --- # 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 operators, hosting providers, and service businesses. Target strengths versus typical SaaS billing tools: - simpler workflow - data ownership - exportability - portability - operator-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 - integration paths for vertical forks such as HVAC/customer-service variants --- # 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.