billing frontend for mariadb. setup as otb_billing for outsidethebox.top accounting. also involved with outsidethedb

6.2 KiB

Raw Blame History

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.

6.2 KiB Raw Blame History