# 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:

1) client self-hosting installs  
2) 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.