Add project state documentation

PROJECT_STATE.md

@@ -0,0 +1,319 @@
+# OTB Billing — Project State
+
+Last Updated: 2026-03-08  
+Version: v0.2.1  
+Server: outsidethedb  
+IP: 192.168.0.24  
+Port: 5050  
+
+---
+
+# Project Purpose
+
+OTB Billing is a self-hosted billing and accounting system for the
+OutsideTheBox infrastructure services.
+
+The system is intended to replace SaaS accounting tools (such as
+QuickBooks) with a fully self-controlled platform capable of managing:
+
+• Hosting clients  
+• Service subscriptions  
+• Infrastructure billing  
+• RPC / blockchain services  
+• IPFS storage services  
+• consulting / development work  
+
+The system will integrate with the broader OutsideTheBox ecosystem.
+
+---
+
+# Current Deployment
+
+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
+
+---
+
+## Services
+
+Service catalog for billable items.
+
+Pages:
+
+/services  
+/service/new  
+/service/<id>/edit
+
+---
+
+## 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.
+
+---
+
+## Payments
+
+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.
+
+---
+
+# Time Handling
+
+Database storage:
+
+UTC
+
+Display:
+
+Eastern Time (Toronto)
+
+---
+
+# Money Formatting
+
+All monetary values are formatted as:
+
+$123.45
+
+Across:
+
+• invoices  
+• payments  
+• ledger  
+• dashboard
+
+---
+
+# Footer
+
+Pages display version:
+
+OTB Billing v0.2.1
+
+---
+
+# Accounting Rules
+
+Invoices are historical documents.
+
+If a payment exists on an invoice:
+
+The invoice becomes locked.
+
+Future corrections must use ledger credits or adjustment documents.
+
+---
+
+# Planned Features
+
+## Overpayment Credit
+
+If payment exceeds invoice total:
+
+Excess amount becomes client ledger credit.
+
+---
+
+## Audit Trail
+
+Track:
+
+• who changed data  
+• when it changed  
+• previous values
+
+---
+
+## Multi-Currency
+
+Currencies planned:
+
+CAD (base ledger)  
+USD  
+EUR
+
+Conversion fees may be applied.
+
+Ledger will settle to CAD.
+
+---
+
+## Email Invoices
+
+Future capability to send invoices directly from the system.
+
+---
+
+## PDF Invoice Generation
+
+Invoices will be exportable as PDF documents.
+
+---
+
+## Tax Support
+
+Support for Canadian tax handling:
+
+HST  
+GST  
+PST (if needed)
+
+---
+
+## Health Monitoring
+
+Future /health endpoint similar to outsidethedb.
+
+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
+
+---
+
+# 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