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.2.1 |
||||
Server: outsidethedb |
||||
IP: 192.168.0.24 |
||||
Port: 5050 |
||||
Version: v0.3-dev |
||||
Status: Active Development |
||||
Backend: Flask (Python) |
||||
Database: MariaDB |
||||
Default Port: 5050 |
||||
Install Location: ~/otb_billing |
||||
|
||||
--- |
||||
|
||||
# Project Purpose |
||||
# Overview |
||||
|
||||
OTB Billing is a self-hosted billing and accounting system for the |
||||
OutsideTheBox infrastructure services. |
||||
OTB Billing is a lightweight contractor-focused billing system designed to be: |
||||
|
||||
The system is intended to replace SaaS accounting tools (such as |
||||
QuickBooks) with a fully self-controlled platform capable of managing: |
||||
- self-hostable |
||||
- deployable via installer |
||||
- database-driven |
||||
- portable across Linux servers |
||||
- simple HTML frontend with strong backend logic |
||||
|
||||
• Hosting clients |
||||
• Service subscriptions |
||||
• Infrastructure billing |
||||
• RPC / blockchain services |
||||
• IPFS storage services |
||||
• consulting / development work |
||||
The system is intended to support both: |
||||
|
||||
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: |
||||
|
||||
/home/def/otb_billing |
||||
|
||||
Server: |
||||
|
||||
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 |
||||
|
||||
--- |
||||
## Client Management |
||||
- create/edit clients |
||||
- client code system |
||||
- client contact details |
||||
- client ledger link |
||||
|
||||
## Services |
||||
|
||||
Service catalog for billable items. |
||||
|
||||
Pages: |
||||
|
||||
/services |
||||
/service/new |
||||
/service/<id>/edit |
||||
|
||||
--- |
||||
- service code system |
||||
- service descriptions |
||||
- reusable services for invoices |
||||
|
||||
## Invoices |
||||
|
||||
Invoices can be created and edited until payments are applied. |
||||
|
||||
Pages: |
||||
|
||||
/invoices |
||||
/invoice/new |
||||
/invoice/<id> |
||||
|
||||
Rule: |
||||
|
||||
Invoices with payments become locked and cannot be edited. |
||||
|
||||
Corrections must be handled using: |
||||
|
||||
• adjustments |
||||
• credits |
||||
• returns |
||||
|
||||
This preserves accounting integrity. |
||||
|
||||
--- |
||||
- 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 |
||||
|
||||
Payments can be added and edited. |
||||
|
||||
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. |
||||
|
||||
--- |
||||
Backend: |
||||
Flask |
||||
|
||||
# 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 |
||||
|
||||
All monetary values are formatted as: |
||||
|
||||
$123.45 |
||||
# Installer Philosophy |
||||
|
||||
Across: |
||||
OTB Billing is designed to support automated installs. |
||||
|
||||
• invoices |
||||
• payments |
||||
• ledger |
||||
• dashboard |
||||
Target workflow: |
||||
|
||||
--- |
||||
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 |
||||
|
||||
Invoices are historical documents. |
||||
|
||||
If a payment exists on an invoice: |
||||
# Security Considerations |
||||
|
||||
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 |
||||
|
||||
## Overpayment Credit |
||||
|
||||
If payment exceeds invoice total: |
||||
|
||||
Excess amount becomes client ledger credit. |
||||
|
||||
--- |
||||
|
||||
## Audit Trail |
||||
## Near Term |
||||
|
||||
Track: |
||||
Email invoices |
||||
- attach generated PDF |
||||
- send via configured SMTP |
||||
|
||||
• who changed data |
||||
• when it changed |
||||
• previous values |
||||
Invoice defaults |
||||
- default currency |
||||
- 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) |
||||
USD |
||||
EUR |
||||
Quotes / estimates |
||||
Recurring invoices |
||||
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 |
||||
|
||||
Support for Canadian tax handling: |
||||
# Repository Discipline |
||||
|
||||
HST |
||||
GST |
||||
PST (if needed) |
||||
Every version bump must: |
||||
|
||||
--- |
||||
- 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: |
||||
|
||||
• 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 |
||||
This ensures reliable rollback and historical tracking. |
||||
|
||||
--- |
||||
|
||||
# Development Philosophy |
||||
|
||||
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 |
||||
End of file. |
||||
|
||||
Loading…
Reference in new issue