Core Entities

Core entities separate platform access from real-world business identity. The central concept is parties: every person, company, agency, provider, administrator, and authority should be represented as a party.

parties

Purpose

Central business identity entity. A party can be a physical person or a company.

It can represent a landlord, tenant, guarantor, property manager, service provider, agency, accountant, tax authority, condominium administrator, or utility provider.

Suggested attributes

Field	Description
id	Primary identifier.
party_type	PERSON or COMPANY.
first_name	Person first name. Nullable for companies.
last_name	Person last name. Nullable for companies.
company_name	Legal or commercial company name. Nullable for persons.
fiscal_code	Italian fiscal code or equivalent identifier.
vat_number	VAT number for companies or professionals.
date_of_birth	Birth date for physical persons.
place_of_birth	Birth place for physical persons.
nationality	Nationality or country code.
email	Business contact email.
phone	Business contact phone.
address	Street address.
city	City.
country	Country.
notes	Free-form operational notes.
created_at	Creation timestamp.
updated_at	Last update timestamp.

Relationships

Relationship	Description
parties to users	One party may have zero, one, or many platform users.
parties to property_parties	One party may be linked to many properties with different roles.
parties to contract_parties	One party may be linked to many contracts with different roles.
parties to bank_account_holders	One party may hold or co-hold many logical bank accounts.
parties to service_provider_profiles	One party may be extended as a service provider.

Notes and design rationale

parties is the business identity table. It prevents duplicate identity models such as separate landlord, tenant, supplier, and agency tables. Role-specific meaning is expressed through relationship tables.

users

Purpose

Existing platform authentication table. It stores login data, access data, password credentials, and future authorization metadata.

Suggested attributes

The existing application owns the exact structure of users. The target model requires only the following conceptual link.

Field	Description
id	Existing user identifier.
party_id	Nullable foreign key to parties.id for legacy compatibility.

Relationships

Relationship	Description
users.party_id to parties.id	Many users may belong to the same party.

Notes and design rationale

Users are not the business identity. They are login identities. party_id may be nullable for legacy users, but every active platform user should eventually be linked to one party.

A company party can have multiple users with different platform profiles or permissions in the future.

roles

Purpose

Defines the available platform roles. A role represents a functional profile that determines what a user can see and do on the platform.

Attributes

Field	Description
id	Primary identifier.
code	Unique role code (e.g. ADMIN, DEV, OWNER, MANAGER, VIEWER).
name	Human-readable role name.
description	Description of the role scope and access level.
is_active	Whether the role is currently assignable.
created_at	Creation timestamp.

Default roles

Code	Name	Scope
ADMIN	Amministratore	Full platform access including configuration.
DEV	Sviluppatore	Access to technical sections, logs, and system tools.
OWNER	Proprietario	Management of own properties, contracts, and transactions.
MANAGER	Gestore	Delegated operational access to assigned properties and contracts.
VIEWER	Visualizzatore	Read-only access to authorised data.

Relationships

Relationship	Description
roles to user_roles	One role can be assigned to many users.

user_roles

Purpose

Many-to-many join table between users and roles. One user can hold multiple roles simultaneously. Each assignment records who granted it and when.

Attributes

Field	Description
id	Primary identifier.
user_id	Platform user receiving the role. References users.id.
role_id	Role being assigned. References roles.id.
granted_by_user_id	User who granted the assignment. Nullable (system-assigned on bootstrap).
created_at	Timestamp of the assignment.

Constraints

Constraint	Description
UNIQUE (user_id, role_id)	A user cannot hold the same role twice.

Relationships

Relationship	Description
user_roles.user_id to users.id	Many role assignments can belong to one user.
user_roles.role_id to roles.id	Many users can share the same role.
user_roles.granted_by_user_id to users.id	Audit link to the granting user.

Notes and design rationale

Roles are defined centrally in roles and assigned via user_roles. This allows multi-role users (e.g. a user who is both OWNER and MANAGER). Role logic is enforced at the application layer — the database only stores the assignment.

service_provider_profiles

Purpose

Extends parties when a party acts as a service provider. The provider remains a party and can still appear in other roles.

Examples include electricity providers, gas providers, water providers, internet providers, phone providers, condominium administrators, tax authorities, insurance companies, maintenance companies, and agencies.

Suggested attributes

Field	Description
id	Primary identifier.
party_id	Provider party.
provider_type	ENERGY, GAS, WATER, INTERNET, PHONE, CONDOMINIUM, TAX_AUTHORITY, INSURANCE, MAINTENANCE, AGENCY, or OTHER.
vat_number	Provider VAT number if different or normalized separately.
customer_service_email	Support email.
customer_service_phone	Support phone.
website	Provider website.
notes	Operational notes.

Relationships

Relationship	Description
service_provider_profiles.party_id to parties.id	Each provider profile belongs to one party.
property_services.provider_party_id to parties.id	Services reference the provider party directly.

Notes and design rationale

Provider details are optional and role-specific. They should not pollute the base parties table.

Graphical local diagrams

parties

users / roles / user_roles

service_provider_profiles