Tenancy & Property Data Model

Introduced in v0.1.16

Overview

The Tenancy & Property Data Model is the foundational layer of the platform. It defines the core domain entities — properties, tenancies, tenancy periods, landlords, tenants, and letting agents — and the relationships between them. All deposit management, dispute resolution, and compliance workflows are built on top of these models.

Core Entities

Property

A Property represents a single rentable unit (e.g. a flat, house, or room). It is the physical asset at the centre of every tenancy.

Field	Description
`id`	Unique identifier
`address`	Full address of the property
`landlord_id`	Reference to the owning Landlord
`agent_id`	Optional reference to a managing Letting Agent

Tenancy

A Tenancy represents the formal agreement between one or more tenants and a landlord (or their agent) for occupation of a property.

Field	Description
`id`	Unique identifier
`property_id`	Reference to the associated Property
`landlord_id`	Reference to the Landlord
`agent_id`	Optional reference to a Letting Agent
`status`	Current state of the tenancy (e.g. active, ended)

Tenancy Period

A Tenancy Period represents a discrete, date-bounded interval within a tenancy — for example, a fixed-term period followed by a statutory periodic tenancy.

Field	Description
`id`	Unique identifier
`tenancy_id`	Reference to the parent Tenancy
`start_date`	Period start date
`end_date`	Period end date (nullable for open-ended periods)
`type`	Period type (e.g. `fixed`, `periodic`)

Landlord

A Landlord is the legal owner of a property who enters into a tenancy agreement.

Field	Description
`id`	Unique identifier
`name`	Full name or company name
`email`	Contact email address
`phone`	Contact phone number (optional)

Tenant

A Tenant is an individual named on a tenancy agreement as an occupant.

Field	Description
`id`	Unique identifier
`name`	Full name
`email`	Contact email address
`tenancy_id`	Reference to the associated Tenancy

Letting Agent

A Letting Agent is a third-party agency acting on behalf of a landlord in managing a property or tenancy.

Field	Description
`id`	Unique identifier
`name`	Agency name
`email`	Contact email address
`phone`	Contact phone number (optional)

Entity Relationships

Landlord ──┐
           ├──> Property ──> Tenancy ──> Tenancy Period
Agent ─────┘                   │
                               └──> Tenant(s)

A Landlord owns one or more Properties.
A Letting Agent optionally manages one or more Properties or Tenancies on a landlord's behalf.
A Property can have multiple Tenancies over time (sequential, never overlapping).
A Tenancy has one or more Tenancy Periods and one or more Tenants.

Database Migration

This release introduces a new schema. A migration must be applied before deploying v0.1.16:

# Example — exact command depends on your migration tooling
npx prisma migrate deploy
# or
npm run db:migrate

The migration is additive only — no existing tables are modified or removed.

API Endpoints

Initial CRUD endpoints are available for all core entities. All endpoints are authenticated and scoped to the requesting user's organisation.

Method	Path	Description
`POST`	`/api/properties`	Create a property
`GET`	`/api/properties/:id`	Get a property
`POST`	`/api/tenancies`	Create a tenancy
`GET`	`/api/tenancies/:id`	Get a tenancy
`POST`	`/api/tenancies/:id/periods`	Add a tenancy period
`GET`	`/api/landlords/:id`	Get a landlord
`GET`	`/api/tenants/:id`	Get a tenant
`GET`	`/api/agents/:id`	Get a letting agent

Full request/response schemas will be documented in the API Reference as endpoints are stabilised.

What This Unlocks

With the core data model in place, the following capabilities can now be built:

Deposit management — linking deposits to specific tenancies and periods.
Check-in / check-out reports — associated with a property and tenancy period.
Deduction claims — raised against a tenancy by a landlord or agent.
Dispute resolution workflows — tied to a tenancy, its parties, and the evidence on record.
Renters' Rights Act compliance checks — validated against tenancy period dates and party details.