Documentation Index
Fetch the complete documentation index at: https://docs.wellapp.ai/llms.txt
Use this file to discover all available pages before exploring further.
PersonLocation is a pivot (bridge) entity that links a People record to a Location record, recording whether that address is the person’s primary address and whether it serves a legal purpose. It mirrors the company_locations pattern applied to individuals. The entity is workspace-scoped indirectly through its owning People record, carries soft-delete semantics via deleted_at, and enforces a partial-unique constraint ensuring at most one primary address per person among non-deleted rows.
| Naming | Value |
|---|
| Object | PersonLocation |
Resource type (JSON:API type) | person_location |
| Collection / records root | — (not a records root) |
| REST base | /v1/person-locations |
| Entity class | PersonLocation |
Internal object. Not currently exposed on the public REST API. The operations below describe the intended contract.
API operations
| Operation | Method & path | Status |
|---|
| List | GET /v1/person-locations | 🟡 Planned |
| Retrieve | GET /v1/person-locations/{id} | 🟡 Planned |
| Create | POST /v1/person-locations | 🟡 Planned |
| Update | PATCH /v1/person-locations/{id} | 🟡 Planned |
| Delete | DELETE /v1/person-locations/{id} | 🟡 Planned |
Data model
Attributes
| Field | Type | Required | Constraints | Allowed values | Description |
|---|
| is_primary | boolean | ✅ Yes | Partial unique index: only one row per person_pk may have is_primary = TRUE where deleted_at IS NULL (index uniq_person_locations_primary_person) | true | false | Marks this address as the person’s primary (canonical) address. At most one non-deleted PersonLocation per person may be primary. |
| is_legal | boolean | ✅ Yes | Not null | true | false | Indicates whether this address is the person’s legal domicile (registered address for official/legal purposes). |
| label | string | ✅ Yes | varchar(255), not null | — | Human-readable label categorising the address (e.g. ‘Home’, ‘Work’, ‘Billing’). Free-form text up to 255 characters. |
| created_at | 🔒 system — Date | ✅ Yes | timestamptz, set on insert via onCreate hook, never updated | — | Timestamp when this pivot row was created. System-set on insert; not writable by the user. |
| deleted_at | Date | null | ⚪ No | timestamptz, nullable; NULL means active; partial indexes filter WHERE deleted_at IS NULL | — | Soft-delete timestamp. When set, the row is logically deleted and excluded from all active queries. System-managed; not directly patchable. |
Relationships
| Name | Type | Required | Description |
|---|
| person | to-one (ManyToOne) | ✅ Yes | The People record this address is attached to. Foreign key person_pk → core_api.people.pk. Indexed via partial index idx_person_locations_person (WHERE deleted_at IS NULL). |
| location | to-one (ManyToOne) | ✅ Yes | The Location record (address details) associated with this pivot. Foreign key location_pk → core_api.locations.pk. Indexed via idx_person_locations_location. |
System-computed
- pk — auto-increment serial integer, internal join key only; never exposed on the public API.
- created_at — set to new Date() via @Property() on insert; no subsequent updates (no updated_at column on this entity).
- deleted_at — soft-delete sentinel; null on creation; set by the application soft-delete service, never by user PATCH.
- Partial unique index uniq_person_locations_primary_person enforces at most one is_primary = TRUE row per person_pk among non-deleted rows — maintained by the database, not application code.
- The entity has no updated_at column; mutations that change is_primary or label do not produce a timestamp trail beyond created_at.
- No UUID public id column — PersonLocation does not carry a *_id UUID field; it is identified externally via the combination of person relationship + location relationship.
- No workspace_pk column — tenant isolation is inherited transitively through the person → workspace path; Hasura RLS walks this relationship chain.
Example
{
"data": {
"type": "person_location",
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"attributes": {
"is_primary": true,
"is_legal": false,
"label": "Home",
"created_at": "2025-09-14T10:23:00.000Z",
"deleted_at": null
},
"relationships": {
"person": {
"data": { "type": "people", "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }
},
"location": {
"data": { "type": "location", "id": "f9e8d7c6-b5a4-3210-fedc-ba9876543210" }
}
}
}
}
apps/api/src/database/entities/PersonLocation.ts · domain: financial-graph · tier: Supporting
