Customers, contacts and recipient roles
A customer is a household or an organization with a relationship to the company providing the service. A contact is a person linked to that customer. Contact, quote recipient, invoice recipient and household-work deduction recipient are separate roles. One person can hold several roles, but selecting one role does not establish the others.
Toolora separates shared party identity from the active company’s relationship and private profile. The customer’s projects refer to that party within their own company context. A contact relationship does not itself grant customer portal access.
Identity and company ownership
Section titled “Identity and company ownership”The record model connects these identities with their key, scope and enforcement rules across commercial and financial records.
| Record | Owns | Relationship and cardinality |
|---|---|---|
parties, with organizations or persons |
Shared identity and party kind | A party can be referenced by several companies. A party UUID is not a login or a company membership. |
party_tenant_relationships (PTR) |
One company’s customer relationship, status, responsibility, payment settings and recipient defaults | At most one row per party/company pair. Relationship types include leads as well as customers; is_customer determines the customer classification. |
organization_tenant_profiles, household_tenant_profiles |
Company-specific customer presentation | Profiles belong to a company and the relevant organization/household. A household has no organization number; its local profile supplies its name and address. |
person_tenant_profiles |
A company’s contact name, email and phone for a person-party | At most one profile per company/person-party pair. Several customer memberships in that company can use the same profile. |
party_memberships |
The person’s role at one customer, title, validity dates and primary-contact flag | Unique company/person/customer combination. A person can have several customer memberships; a customer can have several contacts. |
auth.users, people |
Login identity and the person’s membership in a company | These support authentication, staff/worker roles and capabilities. A contact profile can exist without either a login or a people row. |
flowchart TD C[Company] -->|0..many| R[Customer relationships] R -->|exactly one| P[Shared household or organization party] C -->|0..many| CP[Customer profiles] CP --> P C -->|0..many| M[Customer memberships] M -->|one customer| P M -->|one person| PP[Shared person-party] C -->|0..many| TP[Contact profiles] TP -->|one person| PP C -->|0..many| PE[People company memberships] PE --> PP PE -->|optional login link| U[Auth user]
Sharing a party does not share a company’s contact details, notes or commercial relationship. Reads must retain company scope; resource authorization is separate from the existence of a foreign key. Display views resolve current presentation; they do not own the customer or replace its underlying records.
Creating a customer or contact
Section titled “Creating a customer or contact”Current customer creation uses an organization or household. Even a private customer consisting of one person uses a household customer and a person contact. The database’s person-PTR trigger rejects new bare-person customer relationships. Existing person-customer rows can still appear through historical read compatibility. They are not a pattern for new customer creation.
The organization helper can reuse an organization identified by its Swedish
registration number and adds the company relationship if absent. Company profile
edits remain separate from shared organization identity. A household has no
equivalent natural registration key. The current form uses
create_household_with_first_member with a request UUID: customer creation and
the optional first member commit together, and the same actor/request can retry
the same input without creating another household.
For household contacts, add_household_member creates a distinct person from an
explicit request identity. Alex and Sam can share household@example.test and
remain two people. Reusing a request UUID with different input is rejected.
link_existing_person_to_household instead links a specifically selected active,
non-worker staff person in the company. It preserves an existing active
membership and seeds a contact profile only if missing. This operation is not
a general email-based identity merge.
Organization contact creation still uses ensure_person_contact. That legacy
body looks for a case-insensitive email match in the company’s contact profiles
and can reuse and update the matched person’s profile. It differs from explicit
household identity creation. Do not assume every contact path preserves two
people who share an email address. Changing organization identity matching
requires its own migration and product decision.
Import identifiers are also scoped. A household profile’s non-null
source_external_id is unique within its company. The later
bygglet_customer_refs table can map several source customer IDs to one party;
one profile field is therefore not an exhaustive record of imported identities.
These constraints preserve source references rather than proving current contact
or agreement authority.
Contact editing and membership validity
Section titled “Contact editing and membership validity”Membership validity uses inclusive valid_from and valid_to dates; a missing
endpoint is open. The contact list can include historical memberships. Recipient
selection considers the currently valid ones. A primary flag is a selection
hint, not a guarantee that exactly one primary contact exists.
The contact editor updates a company profile and, when requested, the selected
customer membership’s role/title. It binds the membership to the person,
customer and company before saving the profile. Its compensating rollback uses
the same identity scope. Profile editing does not change the Auth email or a
staff people record. Because the profile is per person/company, its current
values are also used by that person’s other customer memberships in the company.
The membership and profile updates are separate HTTP transactions. A failed profile update triggers an attempted membership rollback; this is not a database transaction or a general concurrency guarantee. Profile-only editing checks the membership but leaves its role unchanged. The sent-quote editor can use this path to correct current contact details without modifying an earlier accepted agreement.
Recipient defaults and document choices
Section titled “Recipient defaults and document choices”| Role | Current source | What the role establishes |
|---|---|---|
| Customer contact | PTR contact choice, otherwise one active primary or sole member | Default communication contact. Ambiguous membership sets remain unresolved. |
| Quote recipient | PTR quote choice, otherwise the contact selection | A default for a new quote choice. The quote’s recipients and acceptance evidence have their own lifecycle. |
| Invoice recipient | PTR invoice choice, otherwise the contact selection; explicit invoice_email takes precedence |
Default delivery address. An invoice can have a separate mailbox without a selected person. |
| Deduction recipient | Saved recipient catalogue, then an explicit allocation for the job | Candidate identity and a reviewed share for ROT/RUT. No implicit contact fallback or catalogue default percentages. |
| Portal reader | Customer grant/historical self-access, or an independently qualifying direct project contact under the current portal contract | Admission to customer information, subject to the portal’s own checks and publication. |
Communication-role defaults resolve through v_customer_recipient_roles. For
contact, quote and invoice, an explicit role choice takes precedence, followed
by the saved contact and an unambiguous active member. One active primary wins;
otherwise one sole active member can be used. An explicit choice whose membership
has expired stays unresolved instead of selecting someone else. Invoice delivery
can fall back to the shared organization’s email when there is no selected person;
an explicit billing mailbox still has first priority.
The view’s rot row retains an explicit legacy role field, but the current
recipient editor only offers the three communication roles. The saved deduction
catalogue has its own API, revision and selected people. The current workflow
does not infer a deduction recipient from the communication contact. See
deduction allocations for the financial
subject and its distinct source/evidence limits.
Defaults help create records. They do not continuously rewrite saved documents.
A new native invoice draft captures billing_email_snapshot and
fk_billing_recipient_party. Changing its customer resets those choices through
the draft rules; changing a PTR default does not rewrite an existing invoice.
The invoice guard locks the recipient after numbering, export lock or movement
out of draft. Sent quote and accepted recipient evidence likewise remain owned
by their versioned records. Correcting today’s contact profile is not proof that
an earlier document was sent to the corrected address.
Examples
Section titled “Examples”Alex Example is the contact, quote recipient, invoice recipient and sole selected deduction recipient for Household Example. These choices can all reference Alex’s person-party. The deduction still needs verified person/property data and a job-specific allocation. Current portal admission requires a qualifying customer relation or direct project contact; being a recipient alone supplies neither.
At Example Organization, Alex coordinates work, Sam receives quotes and an accounts mailbox receives invoices. The mailbox need not identify either person. Removing Sam’s current membership makes a saved default unresolved but does not erase an accepted quote or revoke a separate portal grant. Publication determines which project version an admitted reader sees; see publication and record ownership.
Verification scope
Section titled “Verification scope”The focused contact, recipient-editor and work-order hook selection passed 22 frontend tests with substituted Supabase clients. The new membership/person mismatch case fails against the previous role-edit implementation and passes with the person predicate. These tests establish browser query construction and error handling, not live RLS, transaction rollback or concurrent edits.
Database tests for contact isolation/audit, household retries, linking staff and source identity were inspected alongside active migrations. They were not run in this documentation review. The portal reference now owns the November 17 replacement: shared discovery/detail admission over paired live identities, independent customer and direct-project bases, and stronger operation checks. This update supersedes the earlier discovery mismatch; the editor tests above retain their original scope.