Project Description Automated Utility Bill Allocation & Tenant Rebilling System (Odoo Online Integration) 1. Project Purpose The goal of this project is to build a system that automatically processes municipal utility bills and allocates costs per apartment/unit, then re-bills tenants accordingly using Odoo Online. The system is intended for large residential or mixed-use property portfolios where utility billing is currently handled manually due to the lack of suitable off-the-shelf software. 2. Critical Context (Important for Quoting) **Municipal bills are provided as unstructured PDFs.** The PDFs are not machine-generated invoices They are not CSV/Excel They do not contain consistent tables Line items, totals, credits, and references are spread across multiple lines Meter references and monetary values are not always on the same line Any solution must therefore include custom PDF text parsing logic, not simple data import. 3. High-Level End-to-End Workflow From start to finish, the system must: Accept a municipal utility bill (PDF upload) Parse unstructured PDF text Identify utility charges Group charges by meter reference Map meters to units/apartments Allocate costs to the correct Odoo analytic accounts Create a vendor bill in Odoo Automatically re-bill tenants via customer invoices in Odoo 4. Core Concepts 4.1 Units / Apartments Each apartment/unit is represented as an analytic account in Odoo Example: Complex: Villa Estates Unit: 121 Analytic Code: VIL-121 4.2 Utility Meters Each unit has one or more municipal meters (e.g. water meters) Meter numbers appear inconsistently throughout the PDF Each meter must be mapped to a unit 4.3 Tenants Each unit may have a tenant Tenants are standard Odoo contacts Tenant → Unit mapping determines who gets invoiced 5. Functional Requirements 5.1 Admin Interface A web-based admin interface is required to manage: Units Meter → unit mappings Tenant → unit mappings Billing products (water, electricity, etc.) This interface is designed for non-technical administrative users. 5.2 PDF Bill Upload User uploads an unstructured municipal PDF The system stores the file The system extracts raw text from the PDF 5.3 Unstructured PDF Parsing The system must: Identify meter reference blocks (e.g. Reference - W123546) Collect multiple line items associated with a meter Correctly handle: Credits (negative amounts) Adjustments Partial totals Aggregate a final total per meter Ignore unrelated sections of the document This logic must be custom-built, not generic OCR or table extraction. 5.4 Meter → Unit Matching Extracted meter references are matched against stored mappings Unmatched meters must be: Reported to the user Correctable via the admin UI Matched meters proceed to billing 5.5 Vendor Bill Creation (Odoo) The system creates one vendor bill in Odoo per municipal invoice Bill characteristics: One line per meter Correct monetary amount Analytic distribution assigning 100% of each line to the relevant unit Bill can be: Draft, or Automatically posted (configurable) 5.6 Tenant Rebilling Water charges are aggregated per unit For each unit with a tenant: A customer invoice is created in Odoo One invoice line per billing period Units without tenants are skipped and reported Invoices can be: Draft, or Automatically posted (configurable) 6. Odoo Constraints (Non-Negotiable) The solution must work with Odoo Online only. This means: - XML-RPC / API integration only - No custom Odoo modules - No Odoo.sh - No server-side Odoo code All business logic must live outside Odoo. 7. Technical Expectations (Implementation-Agnostic) A complete solution is expected to include: Backend service (e.g. Python-based) Database for persistent mappings: Units Meters Tenants Admin web UI Robust PDF parsing logic Odoo API integration Exact frameworks and tools are flexible. 8. Extensibility Requirements Although the initial scope is water only, the design must support: Electricity billing Rates and refuse Multiple complexes Different municipal bill layouts Historical reconciliation and audit trails 9. Deliverables A full implementation would typically deliver: End-to-end working system Admin UI PDF parsing engine Odoo integration Deployment instructions Basic documentation