# 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