Budget Module - Developer Documentation

Overview

The Budget module manages dental treatment quotes with versioning, digital signatures, and PDF generation. This document describes extension points for future modules and third-party integrations.

Note: The workflow supports an optional sent state: draft → [sent] → accepted → completed. Treatment execution tracking is reserved for a future Treatment Plan module.

---

1. Module Structure

backend/app/modules/budget/
├── __init__.py      # BudgetModule(BaseModule)
├── models.py        # Budget, BudgetItem, BudgetSignature, BudgetHistory
├── schemas.py       # Pydantic schemas
├── router.py        # FastAPI endpoints
├── service.py       # BudgetService, BudgetItemService
├── workflow.py      # BudgetWorkflowService (state machine)
└── pdf.py           # BudgetPDFService (PDF generation)

Dependencies

• clinical - Patient data
• catalog - Treatment catalog items and VAT types

---

2. Data Models

Budget

Field	Type	Description
id	UUID	Primary key
clinic_id	UUID	Multi-tenancy
patient_id	UUID	Associated patient
budget_number	String	"PRES-2024-0001" format
version	Integer	Version number
parent_budget_id	UUID	Previous version link
status	String	Workflow state (see section 3)
valid_from	Date	Start of validity
valid_until	Date	Expiration date
global_discount_type	String	"percentage" or "absolute"
global_discount_value	Decimal	Discount amount
subtotal	Decimal	Sum before discounts
total_discount	Decimal	Total discounts
total_tax	Decimal	Total VAT
total	Decimal	Final amount
insurance_estimate	Decimal	Reserved for insurance module

BudgetItem

Field	Type	Description
id	UUID	Primary key
budget_id	UUID	Parent budget
catalog_item_id	UUID	Treatment reference
unit_price	Decimal	Price snapshot
quantity	Integer	Units
discount_type	String	Line discount type
discount_value	Decimal	Line discount
vat_type_id	UUID	VAT type reference
vat_rate	Float	VAT rate snapshot
line_subtotal	Decimal	Before discount
line_discount	Decimal	Discount amount
line_tax	Decimal	VAT amount
line_total	Decimal	Final line total
tooth_number	Integer	FDI notation
surfaces	JSONB	["M", "O", "D"]
invoiced_quantity	Integer	Qty already invoiced

BudgetSignature

Field	Type	Description
id	UUID	Primary key
budget_id	UUID	Signed budget
signature_type	String	full_acceptance / rejection
signed_items	JSONB	Item IDs signed
signed_by_name	String	Signer name
relationship_to_patient	String	patient/guardian/representative
signature_method	String	click_accept/drawn/external_provider
external_signature_id	String	For external providers
external_provider	String	Provider name

---

3. Workflow States

draft ────────────────────────────────────────────┐
  │                                               │
  ├──→ sent ──→ accepted ──→ completed            │
  │       │                                       │
  │       ├──→ rejected (terminal)                │
  │       │                                       │
  │       └──→ expired (terminal, automatic)      │
  │                                               │
  ├──→ accepted ──→ completed (direct acceptance) │
  │                                               │
  ├──→ rejected (terminal)                        │
  │                                               │
  └──→ cancelled (terminal) ←─────────────────────┘

Status Descriptions

Status	Description
draft	Initial state, budget is editable
sent	Sent to patient (by email or manually), awaiting response
accepted	Patient accepted, ready for treatment and invoicing
completed	All work done (marked manually)
rejected	Patient rejected the budget (terminal)
expired	Validity period passed (terminal, automatic)
cancelled	Cancelled by clinic (terminal)

Valid Transitions

From	To
draft	sent, accepted, rejected, cancelled
sent	accepted, rejected, expired, cancelled
accepted	completed, cancelled
completed	(terminal)
rejected	(terminal)
expired	(terminal)
cancelled	(terminal)

Note: The expired status is set automatically by a scheduled job when valid_until < today for draft and sent budgets.

---

4. Events Published

Other modules can subscribe to these events via the Event Bus.

Budget Lifecycle Events

Event	Payload	When
budget.created	{budget_id, patient_id, clinic_id, total, items}	New budget saved
budget.updated	{budget_id, changes}	Budget modified
budget.sent	{budget_id, send_method, recipient_email}	Budget sent to patient
budget.accepted	{budget_id, signature_id, total}	Budget accepted
budget.rejected	{budget_id, reason, rejected_at}	Budget rejected
budget.cancelled	{budget_id, cancelled_by, reason}	Budget cancelled
budget.completed	{budget_id, completed_at}	Budget marked complete

Budget Item Events

Event	Payload	When
budget.item.added	{budget_id, item_id, catalog_item_id, price}	Item added
budget.item.removed	{budget_id, item_id}	Item removed

Example: Invoice Module Subscriber

class InvoiceModule(BaseModule):
    def get_event_handlers(self) -> dict:
        return {
            "budget.accepted": self._notify_ready_for_invoice,
            "budget.completed": self._check_pending_invoices,
        }

    def _notify_ready_for_invoice(self, data: dict) -> None:
        # Budget is now ready to be invoiced
        pass

---

5. Events Budget Module Listens To

Event	Source Module	Action
odontogram.treatment.performed	Odontogram	Reserved for future treatment plan integration
appointment.completed	Clinical	Reserved for future integration

---

6. Extension Points

6.1 Insurance Module (Future)

Reserved field: budget.insurance_estimate

# Insurance module subscribes to budget.created
def _on_budget_created(self, data: dict) -> None:
    coverage = self.calculate_coverage(data["patient_id"], data["items"])
    # Update budget.insurance_estimate

6.2 External Signature Providers (Future)

Reserved fields in BudgetSignature:

• external_signature_id
• external_provider
• signature_method = "external_provider"
• signature_data (JSONB)

# E-signature module provides alternative signature flow
if signature_handler := module_registry.get_signature_handler():
    return signature_handler.request_signature(budget, signer_info)
else:
    return self._click_to_accept(budget, signer_info)

6.3 Treatment Plan Module (Future)

When a Treatment Plan module is implemented:

• Budget items can be linked to treatment plan items
• Treatment execution will be tracked in the plan, not the budget
• Budget remains a commercial document (quote/invoice)

6.4 PDF Template Customization

# Third-party module can add PDF context
class InsuranceModule(BaseModule):
    def get_pdf_extensions(self, document_type: str) -> dict | None:
        if document_type == "budget":
            return {
                "insurance_info": self._get_insurance_section,
                "coverage_breakdown": self._get_coverage_table
            }
        return None

---

7. API Endpoints

CRUD

Method	Endpoint	Permission	Description
GET	/api/v1/budget/budgets	budget.read	List with filters
GET	/api/v1/budget/budgets/{id}	budget.read	Get with items
POST	/api/v1/budget/budgets	budget.write	Create
PUT	/api/v1/budget/budgets/{id}	budget.write	Update (draft only)
DELETE	/api/v1/budget/budgets/{id}	budget.admin	Soft delete

Workflow

Method	Endpoint	Permission	Description
POST	/budgets/{id}/send	budget.write	Send to patient (email or manual)
POST	/budgets/{id}/accept	budget.write	Accept with signature
POST	/budgets/{id}/reject	budget.write	Reject
POST	/budgets/{id}/cancel	budget.write	Cancel
POST	/budgets/{id}/complete	budget.write	Mark completed
POST	/budgets/{id}/duplicate	budget.write	Create new version

Items

Method	Endpoint	Permission	Description
POST	/budgets/{id}/items	budget.write	Add item
PUT	/budgets/{id}/items/{item_id}	budget.write	Update item
DELETE	/budgets/{id}/items/{item_id}	budget.write	Remove item

PDF

Method	Endpoint	Permission	Description
GET	/budgets/{id}/pdf	budget.read	Download PDF
GET	/budgets/{id}/pdf/preview	budget.read	Preview with watermark

Versions & History

Method	Endpoint	Permission	Description
GET	/budgets/{id}/versions	budget.read	List all versions
GET	/budgets/{id}/history	budget.read	Audit history

---

8. Permissions

Permission	Description
budget.read	View budgets
budget.write	Create, edit, workflow actions
budget.admin	Delete budgets

Role Assignments

Role	Permissions
admin	budget.*
dentist	budget.*
hygienist	budget.read
assistant	budget.read, budget.write
receptionist	budget.read, budget.write

---

9. Frontend Components

Pages

• /budgets - List with search and filters
• /budgets/new - Create with patient selection
• /budgets/[id] - Detail/editor view

Components

Component	Purpose
BudgetStatusBadge.vue	Status indicator
BudgetItemModal.vue	Add items from catalog
BudgetFilters.vue	Search and filter controls

Composable

const {
  // State
  budgets, currentBudget, isLoading, error, total,

  // CRUD
  fetchBudgets, fetchBudget, createBudget, updateBudget, deleteBudget,

  // Items
  addItem, updateItem, removeItem,

  // Workflow
  acceptBudget, rejectBudget, cancelBudget, completeBudget, duplicateBudget,

  // Versions & History
  fetchVersions, fetchHistory,

  // PDF
  downloadPDF, getPDFPreviewUrl,

  // Helpers
  getStatusColor, canEdit, canAccept, canReject, canCancel, canComplete, canDuplicate
} = useBudgets()

---

10. Testing

# Run budget module tests
docker-compose exec backend python -m pytest tests/test_budget.py -v

Key Test Cases

• CRUD operations (create, read, update, delete)
• Workflow transitions (accept, reject, cancel, complete)
• Item management (add, update, remove with totals)
• Discount calculations (line and global)
• Version duplication
• Authentication requirements

---

11. Migration Guide

When extending the budget module:

1. Never modify existing columns - Add new columns or tables
2. Use nullable fields for new required data
3. Publish events for all state changes
4. Keep backward compatibility in API responses
5. Version API endpoints if breaking changes needed

---

12. Future Module Integration Roadmap

Module	Integration Type	Priority	Fields/Events Used
billing	Bidirectional	P0	budget.accepted → create invoice
treatment-plan	Extends	P1	Link items to treatment execution
insurance	Extends	P1	insurance_estimate, policy lookup
financing	Extends	P1	financing_plan_id, payment schedules
e-signature	Replaces	P2	external_signature_id, signature_method
communications	Subscribes	P1	budget.accepted, budget.expired
patient-portal	Exposes	P2	Token-based acceptance flow
analytics	Reads	P2	Budget conversion rates, avg values