Functional contract

Organization structure

Tenants are Organizations. Physical clinics are Locations. Fiscal identity is a Legal Entity, independent of Location. Founder register provisions placeholders. Staff Settings CRUD for Legal Entities and Locations ships.

Founder provision, Settings CRUD, and Location switcher shipped Geocoding not built

Do not model Location as the legal or billing identity. A group can mix sites that share an EIN with acquired or franchise sites that keep their own.

Hierarchy

Organization (tenant / holding) ├── Legal Entity 1 (EIN, legal name, bank, fiscal address, merchant account) │ ├── Location A (clinic downtown) │ └── Location B (clinic north) └── Legal Entity 2 └── Location C (franchise / own EIN)

Level	What it is	Owns
Organization	Customer account and brand umbrella	Staff memberships, master catalog, clients and pets, plan, Location grants
Legal Entity	Tax/legal person (EIN / tax ID)	Invoices, merchant account, POs, tax config, accounting export
Location	Physical site	Hours, rooms, appointments, on-hand stock, cash drawer, card terminals
Staff	Membership of a User in an Organization	Role assignments; founder gets org-wide Organization administrator

An Organization has 1..N Legal Entities and 1..N Locations.
Every Location belongs to exactly one Organization and exactly one Legal Entity.
A Legal Entity belongs to exactly one Organization and may cover one or many Locations.
A User is a login identity and does not belong to an Organization. Clinic membership is a Staff record. A User may have several Staff records in different Organizations.
A Staff record is granted Locations by role assignment (Staff access, RBAC). Organization-scoped roles imply every Location.
SuperUsers are platform operators, not Organization staff.
Founder /register calls Organization.provision!: Organization, Legal Entity, Location placeholders, Staff membership, and org-wide Organization administrator.
Organization administrators CRUD further Legal Entities (legal_name, tax_id) and Locations (name, time zone, address, Legal Entity) at /app/settings. The last Legal Entity and the last Location cannot be destroyed.
Location administrators may edit site fields at granted Locations; they cannot create or destroy Locations or change Legal Entity.

Same-EIN groups, independent-EIN franchises, and mixed MSO / post-acquisition groups are all valid. Adding a newly acquired clinic means attaching a Location, and a new Legal Entity only when that clinic keeps its own tax identity.

Data domains

Domain	Level	Behavior
Clients and pets	Organization	One medical chart per patient, visible from every Location
Master catalog	Organization	One list of services and products; Locations inherit and may override
Inventory on hand	Location	A sale at A decrements A, never B
Purchase orders	Legal Entity	POs in the name of the EIN; one PO may supply several Locations of that entity
Appointments	Location	Slots depend on rooms, equipment, and staff at that site
Invoices	Hybrid	Fiscal header from Location’s Legal Entity; sale attributed to the Location
Cash drawer / terminals	Location	Each site closes its own drawer
Merchant account / payouts	Legal Entity	Card proceeds settle to that entity’s bank
Financial reports	All three	Org view, tax view per entity, operational view per Location

Workspace context

Staff work inside one Organization and one current Location.

One granted Location: always current; hide the switcher.
Several grants: workspace shell has a Location switcher. Switching does not create a second account.
Default current Location: the Organization’s only Location, otherwise the last Location that User used.
Times, “today”, and appointment grids use the current Location’s time_zone, not the server clock.

A SuperUser may select any Organization, then any Location in it. Record how current Location is stored (session, header, or URL) in architecture when implemented.

Clients and pets

Client and pet records are Organization-scoped. A pet that visits Location A and later Location C keeps one chart.

Financial balances are not global:

Receivables belong to the Location (and therefore Legal Entity) that originated the invoice.
If a client with an open balance at C presents at A, show an alert. Do not auto-apply that balance to A’s invoice or net it across Legal Entities.
A payment taken at a Location is attributed to that Location and that Location’s Legal Entity.

Plan implications

The data model allows 1..N Legal Entities. Plan caps and Settings UX follow the tier:

Plan	Legal Entities	Locations UX
Starter / Business	Exactly one; fields edited on Settings → Organization (1–1)	Listed under the Organization; no Legal Entity picker
Elite	Unlimited; Settings → Legal Entities CRUD	May assign Locations to a Legal Entity

Acceptance (when built)

Creating an Organization (Organization.provision!) creates at least one Legal Entity and one Location. Shipped for founder register.
A Location cannot exist without a Legal Entity.
The last Legal Entity and the last Location in an Organization cannot be destroyed. Shipped.
Moving a Location to another Legal Entity is an Organization administrator action at Settings → Locations. Shipped. Invoices already issued keep the original entity (invoice module not built).
Staff with grants to A and B can switch in one session and see each site’s schedule and stock, and the same patient chart.
Staff granted only A cannot select B.
A pet treated at two Locations shows one medical history.
An invoice issued at Location C shows Legal Entity 2’s legal name and tax ID, not Legal Entity 1’s.

Out of scope here: payment-processor onboarding, accounting-export field maps. Appointment booking and SOAP UX are defined in their own functional pages.