From 81b2037f1e17742e0abfdeace3b519a65ed04a6e Mon Sep 17 00:00:00 2001 From: def Date: Mon, 9 Mar 2026 03:16:58 +0000 Subject: [PATCH] Add PROJECT_STATE.md and update project architecture summary --- PROJECT_STATE.md | 422 +++++++++++++++++++---------------------------- 1 file changed, 172 insertions(+), 250 deletions(-) diff --git a/PROJECT_STATE.md b/PROJECT_STATE.md index 41cfc79..569b0a8 100644 --- a/PROJECT_STATE.md +++ b/PROJECT_STATE.md @@ -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//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//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/ - -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//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.