1 changed files with 172 additions and 250 deletions
@ -1,319 +1,241 @@ |
|||||||
# OTB Billing — Project State |
# OTB Billing – Project State |
||||||
|
|
||||||
Last Updated: 2026-03-08 |
Version: v0.3-dev |
||||||
Version: v0.2.1 |
Status: Active Development |
||||||
Server: outsidethedb |
Backend: Flask (Python) |
||||||
IP: 192.168.0.24 |
Database: MariaDB |
||||||
Port: 5050 |
Default Port: 5050 |
||||||
|
Install Location: ~/otb_billing |
||||||
|
|
||||||
--- |
--- |
||||||
|
|
||||||
# Project Purpose |
# Overview |
||||||
|
|
||||||
OTB Billing is a self-hosted billing and accounting system for the |
OTB Billing is a lightweight contractor-focused billing system designed to be: |
||||||
OutsideTheBox infrastructure services. |
|
||||||
|
|
||||||
The system is intended to replace SaaS accounting tools (such as |
- self-hostable |
||||||
QuickBooks) with a fully self-controlled platform capable of managing: |
- deployable via installer |
||||||
|
- database-driven |
||||||
|
- portable across Linux servers |
||||||
|
- simple HTML frontend with strong backend logic |
||||||
|
|
||||||
• Hosting clients |
The system is intended to support both: |
||||||
• Service subscriptions |
|
||||||
• Infrastructure billing |
|
||||||
• RPC / blockchain services |
|
||||||
• IPFS storage services |
|
||||||
• consulting / development work |
|
||||||
|
|
||||||
The system will integrate with the broader OutsideTheBox ecosystem. |
1) client self-hosting installs |
||||||
|
2) managed hosted deployments under outsidethebox.top |
||||||
|
|
||||||
--- |
--- |
||||||
|
|
||||||
# Current Deployment |
# Current Core Features |
||||||
|
|
||||||
Location: |
## Client Management |
||||||
|
- create/edit clients |
||||||
/home/def/otb_billing |
- client code system |
||||||
|
- client contact details |
||||||
Server: |
- client ledger link |
||||||
|
|
||||||
outsidethedb |
|
||||||
192.168.0.24 |
|
||||||
|
|
||||||
Backend: |
|
||||||
|
|
||||||
python3 backend/app.py |
|
||||||
|
|
||||||
Port: |
|
||||||
|
|
||||||
5050 |
|
||||||
|
|
||||||
Access URL: |
|
||||||
|
|
||||||
http://192.168.0.24:5050 |
|
||||||
|
|
||||||
--- |
|
||||||
|
|
||||||
# Current Version |
|
||||||
|
|
||||||
v0.2.1 |
|
||||||
|
|
||||||
--- |
|
||||||
|
|
||||||
# Features Implemented |
|
||||||
|
|
||||||
## Clients |
|
||||||
|
|
||||||
Create, edit and list clients. |
|
||||||
|
|
||||||
Pages: |
|
||||||
|
|
||||||
/clients |
|
||||||
/client/new |
|
||||||
/client/<id>/edit |
|
||||||
|
|
||||||
--- |
|
||||||
|
|
||||||
## Services |
## Services |
||||||
|
- service code system |
||||||
Service catalog for billable items. |
- service descriptions |
||||||
|
- reusable services for invoices |
||||||
Pages: |
|
||||||
|
|
||||||
/services |
|
||||||
/service/new |
|
||||||
/service/<id>/edit |
|
||||||
|
|
||||||
--- |
|
||||||
|
|
||||||
## Invoices |
## Invoices |
||||||
|
- automatic invoice numbering (INV-####) |
||||||
Invoices can be created and edited until payments are applied. |
- invoice creation |
||||||
|
- invoice editing |
||||||
Pages: |
- invoice locking when payments exist |
||||||
|
- issued / due dates |
||||||
/invoices |
- invoice status system |
||||||
/invoice/new |
|
||||||
/invoice/<id> |
Statuses: |
||||||
|
- draft |
||||||
Rule: |
- pending |
||||||
|
- partial |
||||||
Invoices with payments become locked and cannot be edited. |
- paid |
||||||
|
- overdue |
||||||
Corrections must be handled using: |
- cancelled |
||||||
|
|
||||||
• adjustments |
|
||||||
• credits |
|
||||||
• returns |
|
||||||
|
|
||||||
This preserves accounting integrity. |
|
||||||
|
|
||||||
--- |
|
||||||
|
|
||||||
## Payments |
## 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 |
||||||
|
|
||||||
Payments can be added and edited. |
Backend: |
||||||
|
Flask |
||||||
Pages: |
|
||||||
|
|
||||||
/payments |
|
||||||
/payment/new |
|
||||||
/payment/<id>/edit |
|
||||||
|
|
||||||
Payments automatically update invoice balances. |
|
||||||
|
|
||||||
--- |
|
||||||
|
|
||||||
## Client Ledger |
|
||||||
|
|
||||||
Each client has a ledger showing: |
|
||||||
|
|
||||||
• charges |
|
||||||
• payments |
|
||||||
• credits |
|
||||||
• running balance |
|
||||||
|
|
||||||
Ledger link is visible from: |
|
||||||
|
|
||||||
• clients list |
|
||||||
• client edit page |
|
||||||
|
|
||||||
--- |
|
||||||
|
|
||||||
## Ledger Color Coding |
|
||||||
|
|
||||||
Ledger link color indicates balance: |
|
||||||
|
|
||||||
Green → positive balance |
|
||||||
Blue → zero balance |
|
||||||
Red → negative balance |
|
||||||
|
|
||||||
This allows quick visual scanning of account status. |
|
||||||
|
|
||||||
--- |
|
||||||
|
|
||||||
# Time Handling |
Database: |
||||||
|
MariaDB using mysql-connector-python |
||||||
|
|
||||||
Database storage: |
PDF Engine: |
||||||
|
ReportLab |
||||||
|
|
||||||
UTC |
Dependencies defined in: |
||||||
|
|
||||||
Display: |
requirements.txt |
||||||
|
|
||||||
Eastern Time (Toronto) |
Flask template system used for UI. |
||||||
|
|
||||||
--- |
--- |
||||||
|
|
||||||
# Money Formatting |
# Installer Philosophy |
||||||
|
|
||||||
All monetary values are formatted as: |
|
||||||
|
|
||||||
$123.45 |
|
||||||
|
|
||||||
Across: |
OTB Billing is designed to support automated installs. |
||||||
|
|
||||||
• invoices |
Target workflow: |
||||||
• payments |
|
||||||
• ledger |
|
||||||
• dashboard |
|
||||||
|
|
||||||
--- |
fresh server |
||||||
|
→ run installer |
||||||
|
→ install python dependencies |
||||||
|
→ install MariaDB |
||||||
|
→ create schema |
||||||
|
→ launch application |
||||||
|
|
||||||
# Footer |
The goal is a **single guided install path** so non-expert Linux users can deploy it. |
||||||
|
|
||||||
Pages display version: |
README.md will include: |
||||||
|
|
||||||
OTB Billing v0.2.1 |
- config file explanation |
||||||
|
- installer instructions |
||||||
|
- deployment examples |
||||||
|
|
||||||
--- |
--- |
||||||
|
|
||||||
# Accounting Rules |
# Security Considerations |
||||||
|
|
||||||
Invoices are historical documents. |
|
||||||
|
|
||||||
If a payment exists on an invoice: |
|
||||||
|
|
||||||
The invoice becomes locked. |
Advanced settings such as database credentials should remain outside the main UI and be configured through installer or config file. |
||||||
|
|
||||||
Future corrections must use ledger credits or adjustment documents. |
SMTP credentials are stored in the settings table but are not yet used for sending email. |
||||||
|
|
||||||
--- |
--- |
||||||
|
|
||||||
# Planned Features |
# Planned Features |
||||||
|
|
||||||
## Overpayment Credit |
## Near Term |
||||||
|
|
||||||
If payment exceeds invoice total: |
|
||||||
|
|
||||||
Excess amount becomes client ledger credit. |
|
||||||
|
|
||||||
--- |
|
||||||
|
|
||||||
## Audit Trail |
|
||||||
|
|
||||||
Track: |
Email invoices |
||||||
|
- attach generated PDF |
||||||
|
- send via configured SMTP |
||||||
|
|
||||||
• who changed data |
Invoice defaults |
||||||
• when it changed |
- default currency |
||||||
• previous values |
- default tax rules |
||||||
|
|
||||||
--- |
Business branding |
||||||
|
- configurable business logo |
||||||
|
- invoice header logo |
||||||
|
|
||||||
## Multi-Currency |
Reports |
||||||
|
- outstanding invoices |
||||||
|
- revenue summaries |
||||||
|
- client account statements |
||||||
|
|
||||||
Currencies planned: |
## Medium Term |
||||||
|
|
||||||
CAD (base ledger) |
Quotes / estimates |
||||||
USD |
Recurring invoices |
||||||
EUR |
Invoice reminders |
||||||
|
Client portal |
||||||
|
|
||||||
Conversion fees may be applied. |
## Long Term |
||||||
|
|
||||||
Ledger will settle to CAD. |
Multi-currency handling |
||||||
|
Exchange rate support |
||||||
|
Accounting export (CSV / QuickBooks style) |
||||||
|
API access |
||||||
|
User authentication system |
||||||
|
Role permissions |
||||||
|
|
||||||
--- |
--- |
||||||
|
|
||||||
## Email Invoices |
# Deployment Goals |
||||||
|
|
||||||
Future capability to send invoices directly from the system. |
OTB Billing should support: |
||||||
|
|
||||||
--- |
Self-host installs |
||||||
|
Managed hosting deployments |
||||||
|
Multi-client environments |
||||||
|
|
||||||
## PDF Invoice Generation |
Target integration with: |
||||||
|
|
||||||
Invoices will be exportable as PDF documents. |
outsidethebox.top hosting services. |
||||||
|
|
||||||
--- |
--- |
||||||
|
|
||||||
## Tax Support |
# Repository Discipline |
||||||
|
|
||||||
Support for Canadian tax handling: |
|
||||||
|
|
||||||
HST |
Every version bump must: |
||||||
GST |
|
||||||
PST (if needed) |
|
||||||
|
|
||||||
--- |
- update PROJECT_STATE.md |
||||||
|
- update README.md changelog |
||||||
|
- produce full version snapshot ZIP backup |
||||||
|
|
||||||
## Health Monitoring |
Example: |
||||||
|
|
||||||
Future /health endpoint similar to outsidethedb. |
otb_billing-v0.3.0.zip |
||||||
|
|
||||||
Will report: |
This ensures reliable rollback and historical tracking. |
||||||
|
|
||||||
• application uptime |
|
||||||
• server uptime |
|
||||||
• memory usage |
|
||||||
• disk usage |
|
||||||
• database connection status |
|
||||||
|
|
||||||
--- |
|
||||||
|
|
||||||
# Relationship to OutsideTheBox |
|
||||||
|
|
||||||
This billing system is part of the broader infrastructure platform: |
|
||||||
|
|
||||||
outsidethebox.top |
|
||||||
|
|
||||||
Services billed through this system may include: |
|
||||||
|
|
||||||
• hosting services |
|
||||||
• RPC endpoints |
|
||||||
• blockchain nodes |
|
||||||
• explorer hosting |
|
||||||
• IPFS storage |
|
||||||
• consulting and development |
|
||||||
|
|
||||||
--- |
--- |
||||||
|
|
||||||
# Development Philosophy |
End of file. |
||||||
|
|
||||||
The system must remain: |
|
||||||
|
|
||||||
• self-hosted |
|
||||||
• auditable |
|
||||||
• infrastructure friendly |
|
||||||
• independent from SaaS platforms |
|
||||||
|
|
||||||
The goal is long-term replacement of external billing tools. |
|
||||||
|
|
||||||
--- |
|
||||||
|
|
||||||
# Restart Instructions |
|
||||||
|
|
||||||
Start server: |
|
||||||
|
|
||||||
python3 backend/app.py |
|
||||||
|
|
||||||
Then access: |
|
||||||
|
|
||||||
http://192.168.0.24:5050 |
|
||||||
|
|
||||||
--- |
|
||||||
|
|
||||||
# Notes |
|
||||||
|
|
||||||
Always update this file when: |
|
||||||
|
|
||||||
• version changes |
|
||||||
• architecture changes |
|
||||||
• major features are added |
|
||||||
• deployment changes |
|
||||||
|
|||||||
Loading…
Reference in new issue