Locations Domain
Technical design of multi-location hierarchy and data isolation
Overview
The locations domain is the foundation of multi-tenancy in Danvas. It allows a single team — a Canvas Forge tenant, not a Clerk Organization — to manage multiple physical restaurant locations with strictly isolated operational data.
Database Schema
Locations (locations)
The central entity for physical sites.
| Column | Type | Description |
|---|---|---|
id | text | Primary key (UUID) |
teamId | text | Configured logical tenant identifier; no persisted teams table |
slug | text | URL-friendly identifier (read-only in the UI; change requires a migration) |
name | text | Human-readable name |
address | text | Mailing address (free-form, ≤500 chars) |
timezone | text | IANA timezone (e.g., America/Chicago) — validated by LocationSettingsSchema |
brandColor | text | Hex color used as the accent for the location (e.g., #F59E0B) |
avatarUrl | text | Public URL to a logo/avatar image — surfaced on the location card and settings form |
Multi-location Logic
Active Location Resolution
The application uses a utility getActiveLocation() to determine which site the user is currently interacting with.
- Preference: The user's
primaryLocationIdin their profile. - Context: URL parameters or headers for specific requests.
- Fallback: The first location alphabetically assigned to the user.
Data Isolation
Isolation is enforced at the query level. Every table that stores location-specific data (reports, incidents, shifts) includes a locationId column.
// Example: Fetching reports for current location
const activeLocation = await getActiveLocation();
const locationReports = await db.query.serverReports.findMany({
where: and(
eq(serverReports.teamId, teamId),
eq(serverReports.locationId, activeLocation.id)
)
});User Permissions
Users are linked to locations via the locationIds array in the users table.
- Global Admin: Can access all locations within the team.
- Location Manager: Can access specific locations listed in their profile.
- Staff: Typically assigned to a single primary location but can be authorized for multiple.