Skip to content

Sub-Domain Blueprint: Community Financials

Domain: Community (governance, occupancy, registry, financials) Logical Sub-Domain: Financials (Obligations) Physical Packages: @sd/mod-community/assessments, @sd/mod-community/contracts Related Documents: Data Definition Context: This document defines the Dues Generation, Penalty Enforcement, and Legal Contracts that drive revenue. Status: Stable (v2.5)

1. Mandate

The Community Financials Sub-Domain is the Levy Engine. It calculates what is owed by whom, based on the Deed (Indiviso) and Assessment Policies (HOA Budget). It does not handle banking (handled by Finance Domain), but it generates the Billable Entries (AssessmentEntry) that Finance collects.

2. Capabilities

Capability Description Component
Dues Calculation Generating monthly charges based on Indiviso %, SqFt, or Flat Rate. levyAssessment
Penalty Automation Scanning for overdue payments and applying configured Late Fees. triggerLateFees
Deed Registry Tracking Legal Ownership LegalPersona and Voting Weight indiviso. Deed
Lease Tracking Recording Tenant obligations (Rent/dates) for occupancy validation. LeaseAgreement

3. Process Models

A. The Monthly Levy Run

Happy Path: Generating January Dues.

sequenceDiagram
    participant Admin
    participant Service as AssessmentService
    participant Deed as DeedService
    participant DB as Firestore (Entries)

    Admin->>Service: levyAssessment(config="HOA Dues", month=1, year=2026)
    Service->>DB: createEvent("Dues Jan 2026", status="calculating")

    loop Every Unit
        Service->>Deed: getActiveDeed(unitId)
        Deed-->>Service: Indiviso (0.45%)
        Service->>Service: Amount = Budget * 0.0045
        Service->>DB: createEntry({ unit, owner, amount: $450 })
    end

    Service->>DB: updateEvent(status="pending_approval")
    Service-->>Admin: Ready for Review

B. Penalty Trigger (Cron)

Happy Path: Late Fee for 30+ Days Overdue.

sequenceDiagram
    participant Cron
    participant Service as AssessmentService
    participant Rule as PenaltyRule (30 Days / 10%)

    Cron->>Service: triggerLateFees()
    Service->>DB: find(status="posted", daysOverdue > 30)

    loop Every Overdue Entry
        Service->>Service: Calc Penalty (Amount * 0.10)
        Service->>DB: createEntry({ type="penalty", amount: $45, parent=entryId })
    end

4. State Machines

Assessment Event

stateDiagram-v2
    [*] --> Draft
    Draft --> Calculating: Triggered
    Calculating --> PendingApproval: Entries Generated
    PendingApproval --> Posted: Admin Approves
    Posted --> [*]: Sent to Finance

5. Interface Definitions

AssessmentService

  • levyAssessment(eventId, configId, period): Promise<Event>
  • postAssessment(eventId): Promise<void>
  • triggerLateFees(period): Promise<void>

DeedService

  • getDeedByAssetId(assetId): Promise<Deed>

6. Changelog

Date Author Description Reference
2026-01-24 Antigravity Initial creation Implementation Plan