Data Definition Document: 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: Process Blueprint Context: This document defines the Data Structures for Deeds, Leases, and Dues. Source: packages/modules/community/src/{assessments,contracts}/schema.ts

0. Entity Relationship Diagram (ERD)

erDiagram
    DEED ||--o{ LEGAL_PERSONA : "owned_by"
    DEED ||--o{ ASSET : "governs"

    ASSESSMENT_CONFIG ||--o{ ASSESSMENT_EVENT : "defines"
    ASSESSMENT_EVENT ||--o{ ASSESSMENT_ENTRY : "generates"

    ASSESSMENT_ENTRY }o--|| DEED : "charged_to"
    PENALTY_RULE ||--o{ ASSESSMENT_ENTRY : "triggers_if_late"

    DEED {
        string id PK
        float indiviso "Voting Weight"
        enum usage "owner_occupied, rental"
    }

    ASSESSMENT_ENTRY {
        string id PK
        float amount
        string identityId "Responsible Payer"
        enum status "pending, posted, collected"
    }

1. Primary Entities

Entity: Deed

The legal contract establishing ownership of a Unit.

Field	Type	Required	Description
id	string	Yes	Unique ID.
assetId	string	Yes	The Unit.
owners	LegalPersona[]	Yes	List of individuals/companies.
indiviso	float	Yes	% Ownership of Common Areas (Critical for Dues/Voting).
usageType	string	Yes	owner_occupied, short_term_rental.
active	boolean	Yes	Soft-delete flag.

Entity: AssessmentEvent

A billing run (e.g. "January 2026 Dues").

Field	Type	Required	Description
configId	string	Yes	Link to Policy (AssessmentConfig).
totalLevied	number	Yes	Sum of all entries.
status	string	Yes	draft, calculating, pending_approval, posted.
period	object	Yes	{ month: 1, year: 2026 }.

Entity: AssessmentEntry

A specific line item charge for a Unit.

Field	Type	Required	Description
eventId	string	Yes	The batch run.
assetId	string	Yes	The target Unit.
identityId	string	Yes	The person billed (from Deed).
amount	number	Yes	The fee.
status	string	Yes	pending, posted (sent to Finance), reversed.

2. Configuration Entities

Entity: AssessmentConfig

Policy Rule for Billing.

Field	Type	Required	Description
calculationMethod	string	Yes	flat_rate, per_m2, indiviso_percentage.
baseAmount	number	Yes	The rate multiplier.

Entity: PenaltyRule

Late Fee Logic.

Field	Type	Required	Description
triggerDaysPastDue	number	Yes	e.g. 30 days.
calculationType	string	Yes	percentage (10%) or fixed ($500).
value	number	Yes	The rate.

4. Changelog

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