Entity Relationship Model Overview
This section describes the conceptual entity relationship model for the rental management application. It is intentionally not SQL DDL yet. The goal is to define stable entities, relationships, and design rules that can later be translated into migrations.
The application manages rental properties, landlords, tenants, co-tenants, guarantors, property managers, agencies, service providers, contracts, bank accounts, expected rent, actual bank movements, expenses, utility bills, documents, maintenance requests, reporting, forecasting, and future alerting.
Design principles
| Principle | Meaning |
|---|---|
| Separate login identity from business identity | users authenticate into the platform. parties represent real people or companies in the business model. |
Use parties as the central business identity | Landlords, tenants, providers, agencies, accountants, and companies are all represented by parties. |
| Allow parties without login | A tenant, supplier, tax authority, or condominium administrator may exist only as business data and never access the platform. |
| Allow many users per party | A company party can have multiple platform users. |
| Use role relationship tables | Do not place owner_id, tenant_id, or manager_id directly on properties or contracts. |
| Support multiple roles | One party may be a landlord on one contract, a guarantor on another, and a provider elsewhere. |
| Use line items | Expected rent and actual bank transactions must be split into normalized accounting lines. |
| Govern categories | transaction_categories are mandatory for fiscal and accounting classification. |
| Use tags as optional labels | Tags add flexible metadata but never replace categories. |
| Separate logical and physical banking | bank_accounts represent business bank accounts. banking_sessions represent open-banking connections. |
| Build for automation | The model must support alerts, forecasts, reconciliation, anomaly detection, and Italian tax reporting. |
Main domains
| Domain | Core entities |
|---|---|
| Identity and access | parties, users, service_provider_profiles |
| Real estate assets | properties, property_units, property_parties, property_tax_profiles |
| Contracts | contracts, contract_units, contract_parties |
| Banking | bank_accounts, bank_account_holders, property_bank_accounts, banking_sessions, bank_account_connections, bank_transactions |
| Expected and actual payments | rent_installments, rent_installment_lines, rent_payment_matches, expected_expenses, expense_payment_matches, bank_transaction_splits |
| Classification | transaction_categories, tags, transaction_tags |
| Services and expenses | property_services, utility_bills, utility_consumptions, expenses |
| Documents and operations | documents, maintenance_requests |
| Reporting | SQL views over normalized operational data |
Naming conventions
All entity and field names use snake_case. Primary keys are named id. Foreign keys use the referenced entity name plus _id, for example party_id, property_id, and contract_id.
Enums are documented as uppercase values. They can later become database enums, lookup tables, or constrained strings depending on the persistence strategy.