Entity: client

Entity Definition

• Entity Name: client
• Entity Type: Database table
• Description: The top-level organisational unit in the system. Every building, gauge, user, document and operational record belongs to exactly one client. The client record holds the organisation's identity, system-wide behavioural settings, licence terms and the set of add-on modules enabled for its users. Corresponds to Tenant in the Users & Access domain — one client = one tenant schema.

Note (Users & Access analysis): a client's grouping into client groups is a many-to-many relationship, not a single FK — see clientGroup and clientGroupMembership. This table has no clientGroupId column.

Data Attributes Table

clientGroupId removed. The single nullable FK this page previously carried is replaced by a many-to-many relationship — see clientGroup and clientGroupMembership, and the Client Groups feature analysis.

Attribute Name	Description	Data Type	Default Value	Required (= Nullable)	Unique	Format	Validations	Index	Example
id	Primary key	UUID	Generated in code (app layer)	Yes	Yes	UUID v7	-	Primary Key	018ed0b3-c298-7c7a-96d5-8b36f5a7f8d2
tenantId	Tenant this record belongs to. Required on every entity for organisation-level data separation.	UUID	-	Yes	No	UUID v7	FK → tenant; must exist	name: idx_client_tenantId, type: btree	018fa51f-fda1-79f4-8461-2cb8f1cabc10
name	Display name of the client organisation	String	-	Yes	No	-	Non-empty; max 255 chars	name: idx_client_name, type: btree	Město Brno
type	Classification of the client organisation. Determines which form sections are shown.	Enum	-	Yes	No	See Enum - ClientType	Must be a valid ClientType value	-	municipality
ico	Czech company tax ID (IČO). Populated via ARES lookup.	String	-	No	No	8-digit string	Nullable; if set must be 8 digits	-	44992785
street	Street name of the client's registered address.	String	null	No	No	-	Max 255 characters	-	Náměstí Svobody
houseNumber	House / descriptive number (číslo popisné) of the client's registered address.	String	null	No	No	-	Max 20 characters	-	12
orientationNumber	Orientation number (číslo orientační) of the client's registered address. Optional complement to houseNumber.	String	null	No	No	-	Max 20 characters	-	4a
zip	Postal code of the client's registered address. Used to auto-populate municipality.	String	null	No	No	-	Exactly 5 digits	-	60200
municipality	Municipality of the client's registered address. Auto-populated from zip via ZIP-to-city lookup; can be overridden manually.	String	null	No	No	-	Max 255 characters	-	Brno
lat	Latitude coordinate for meteogram GPS lookup	Float	-	No	No	WGS84 decimal degrees	Nullable; −90 to 90	-	49.1951
lng	Longitude coordinate for meteogram GPS lookup	Float	-	No	No	WGS84 decimal degrees	Nullable; −180 to 180	-	16.6068
population	Reference population count (municipalities). Manually entered.	Integer	-	No	No	-	Nullable; positive integer	-	380000
buildingCountOwned	Total number of buildings owned by the client (manually entered reference value, not derived)	Integer	-	No	No	-	Nullable; positive integer	-	47
otherFacilityCount	Number of other facilities (e.g. shelters, kiosks) owned — manually entered	Integer	-	No	No	-	Nullable; positive integer	-	12
median	Client-specific consumption baseline median used for comparison in reports	String	-	No	No	-	Nullable	-	120
republicMedian	Republic-wide consumption baseline median for comparison in reports	String	-	No	No	-	Nullable	-	145
regionId	Czech administrative region (kraj). Cross-domain reference — no entity page in this domain.	UUID	-	No	No	UUID v7	FK → region; nullable; onDelete SET NULL	name: idx_client_regionId, type: btree	018ed0b3-c298-7c7a-96d5-8b36f5a7f8d2
mainManagerId	Default responsible person; their contact is shown to field workers	UUID	-	No	No	UUID v7	FK → user; nullable; onDelete SET NULL	name: idx_client_mainManagerId, type: btree	018ed0b3-c298-7c7a-96d5-8b36f5a7f8d2
defaultWeatherStationId	Default weather station used for consumption normalisation (degree-days) across all buildings that have no building-level assignment in clientWeatherStation.	UUID	-	No	No	UUID v7	FK → weatherStation; nullable; onDelete SET NULL	name: idx_client_defaultWeatherStationId, type: btree	018ed0b3-c298-7c7a-96d5-8b36f5a7f8d2
electricityDistributorId	Default electricity distributor (from price-decision domain). Fallback for all gauges without a per-gauge override. Cross-domain reference — no entity page in this domain.	UUID	-	No	No	UUID v7	FK → distributor; nullable; onDelete SET NULL	-	018ed0b3-c298-7c7a-96d5-8b36f5a7f8d2
singleElectricityDistributor	When true, all gauges share the client's default electricity distributor; per-gauge overrides are hidden. Cross-feature dependency: when false, each electricity measuring point (OM) must expose an individual distributor field — see Gauge Management feature.	Boolean	false	No	No	-	Nullable	-	false
gasDistributorId	Default gas distributor. Cross-domain reference — no entity page in this domain.	UUID	-	No	No	UUID v7	FK → gasDistributor; nullable; onDelete SET NULL	-	018ed0b3-c298-7c7a-96d5-8b36f5a7f8d2
singleGasDistributor	When true, all gauges share the client's default gas distributor; per-gauge overrides are hidden. Cross-feature dependency: when false, each gas measuring point (OM) must expose an individual distributor field — see Gauge Management feature.	Boolean	false	No	No	-	Nullable	-	false
licenceType	Licence renewal model	Enum	-	Yes	No	See Enum - LicenceType	Must be a valid LicenceType value	-	indefinitePeriod
licenceLevel	Feature access level of the licence	Enum	-	Yes	No	See Enum - LicenceLevel	Must be a valid LicenceLevel value	-	basic
licenceValidTo	Licence expiry date. Required for timeLimit and autoExtension types; ignored for indefinitePeriod.	Timestamp with time zone	-	No	No	ISO 8601	Nullable; if licenceType ≠ indefinitePeriod must be set	-	2026-12-31T23:59:59Z
defaultActionDeadlineDays	Default number of days for auto-generated action deadlines. Falls back to 7 if null.	Integer	-	No	No	-	Nullable; positive integer	-	14
gaugeMonthControlDaySetting	Mode for the monthly reading cycle start day	Enum	firstDay	Yes	No	See Enum - GaugeMonthControlDaySetting	Must be a valid GaugeMonthControlDaySetting value	-	firstDay
gaugeMonthControlDay	Custom day of month for the reading cycle (1–28). Used only when gaugeMonthControlDaySetting = customDay.	Integer	1	Yes	No	-	1–28	-	15
gaugeWeekControlDay	Day of the week on which the weekly reading cycle starts (1=Monday … 7=Sunday)	Integer	1	Yes	No	-	1–7	-	1
displayExpensesWithoutVat	When true, all invoice and report expense values are shown excluding VAT	Boolean	false	Yes	No	-	-	-	false
showPrediction	How many years of consumption prediction to display (0 = none)	Integer	1	Yes	No	-	Must be one of: 0, 1, 2, 3, 9	-	1
includeOtherElementsInPrediction	When true, energy prices and weather data feed into consumption predictions	Boolean	-	No	No	-	Nullable	-	true
defaultSourcePriority	Tenant-level default trust priority for reading sources, used when a gauge's own sourcePriority is null.	String	remote_manual_invoice	Yes	No	See enum page	Must be one of 6 permutations of remote, manual, invoice	-	remote_manual_invoice
gaugeReadingReminder	Master on/off for gauge reading reminder emails across the whole client	Boolean	true	Yes	No	-	-	-	true
gaugeLimitNotificationDelayHours	Hours before the first limit-overflow notification fires. Falls back to system default if null.	Integer	-	No	No	-	Nullable; positive integer	-	4
gaugeLimitNotificationFrequencyHours	Hours between repeated limit-overflow notifications. Falls back to system default if null.	Integer	-	No	No	-	Nullable; positive integer	-	24
createdAt	Timestamp of when the record was created. Immutable after insert.	Timestamp with time zone	now() — set in code	Yes	No	ISO 8601 — YYYY-MM-DDTHH:mm:ss.SSSZ	Cannot be null; cannot be modified after creation	-	2025-03-16T18:00:00Z
updatedAt	Timestamp of the last update to the record.	Timestamp with time zone	now() — set in code	Yes	No	ISO 8601 — YYYY-MM-DDTHH:mm:ss.SSSZ	Cannot be null	-	2025-03-16T18:00:00Z
deletedAt	Timestamp of soft deletion. Null means the record is active. Once set, this value is immutable.	Timestamp with time zone	-	No	No	ISO 8601 — YYYY-MM-DDTHH:mm:ss.SSSZ	Immutable once set. Active records: WHERE deletedAt IS NULL	-	2025-06-01T09:00:00Z
createdBy	Identifier of the actor who created the record	String	-	Yes	No	type:actor	Non-empty	-	user:018ed0b3-c298-7c7a-96d5-8b36f5a7f8d2
updatedBy	Identifier of the actor who last updated the record	String	-	Yes	No	type:actor	Non-empty	-	system:migration-v25

Source note: the Confluence page describes client as corresponding 1:1 to Tenant/tenant schema, and does not itself mention any platform.clients schema placement — no internal inconsistency was found on the page regarding schema location; flagging per migration instructions only because the topic was called out as a known area of concern elsewhere.

Audited fields

Recorded on created (in full), updated (changed only) and deleted (in full): name, type, ico, street, houseNumber, orientationNumber, zip, municipality, lat, lng, population, buildingCountOwned, otherFacilityCount, median, republicMedian, regionId, mainManagerId, defaultWeatherStationId, electricityDistributorId, singleElectricityDistributor, gasDistributorId, singleGasDistributor, licenceType, licenceLevel, licenceValidTo, defaultActionDeadlineDays, gaugeMonthControlDaySetting, gaugeMonthControlDay, gaugeWeekControlDay, displayExpensesWithoutVat, showPrediction, includeOtherElementsInPrediction, defaultSourcePriority, gaugeReadingReminder, gaugeLimitNotificationDelayHours, gaugeLimitNotificationFrequencyHours.

Excluded: none.

As the top-level organisational unit (1 client = 1 tenant schema, per this entity's own description), a client entry effectively documents every tenant-wide settings change made through the client administration screens — licence terms, module defaults, reading-cycle and notification configuration included.

Not registered for entityName resolution — renders id-only in the audit trail (architecture 61-audit-log.md §7.4 in the code repo: a valid, permanent state, not a gap). If registered, name is the natural candidate.