Entity: clientGroup

Entity Definition

• Entity Name: clientGroup
• Entity Type: Database table, platform schema (platform.client_group)
• Description: A named, flat grouping of client records (e.g. "Plzeňský kraj", "František Dobrota"), used for reporting and to scope a platform-level role's access to a bounded subset of clients. Membership is many-to-many — see clientGroupMembership; a client belongs to zero, one, or several groups, and a group holds zero or more clients up to its own capacity.
• Not tenant data. clientGroup lives in the platform schema alongside platform.clients, with no tenantId — a group is not owned by, or scoped to, any one tenant; it exists to organise clients themselves. This is unrelated to the client → tenant ownership relationship (tenant.clientId, platform.tenants) — see docs/features/em3-44-clients/decision-client-tenant-relationship.md (EM3 code repo, origin/main, 968e59e) in the code repository, which retired the EM2-era hierarchical client_groups (client owning member clients) in favour of client → tenant ownership. This entity is a distinct, narrower concept revived for Client Management: a flat label/tag, never an ownership or delegation relationship, and never consulted for licence, module or billing entitlement.

Data Attributes Table

Attribute Name	Description	Data Type	Default Value	Required (= Nullable)	Unique	Format	Validations	Index	Example
id	Primary key of the entity.	UUID	Generated in code (app layer)	Yes	Yes	UUID v7	-	Primary Key	018fa51f-fda1-79f4-8461-2cb8f1cabc20
name	Human-readable name of the client group.	String	-	Yes	No	-	Non-empty; max 255 chars	name: idx_client_group_name_active, type: btree (active records)	Plzeňský kraj
maxClientCount	Capacity of the group: the maximum number of clients it may hold. Enforced on every membership add — see Client Groups — Functional Requirements.	Integer	-	Yes	No	-	Positive integer (≥ 1); no "unlimited" value — every group states a real cap	-	25
createdAt	Timestamp of when the record was created. Immutable after insert.	Timestamp with time zone	now() — set in code	Yes	No	ISO 8601	Cannot be null; cannot be modified after creation.	-	2026-09-16T00:00:00Z
updatedAt	Timestamp of the last update. Set on insert (equal to createdAt) and updated on every change.	Timestamp with time zone	now() — set in code	Yes	No	ISO 8601	Cannot be null.	-	2026-09-16T00:00:00Z
deletedAt	Timestamp of soft deletion. Null means the record is active. Once set, immutable.	Timestamp with time zone	-	No	No	ISO 8601	Immutable once set. Active records: WHERE deletedAt IS NULL	Indexed (active records)	-
createdBy	Identifier of the actor who created the record.	String	-	Yes	No	type:actor	Non-empty.	-	user:018e...
updatedBy	Identifier of the actor who last updated the record.	String	-	Yes	No	type:actor	Non-empty.	-	user:018e...

Deletion guard: a group cannot be deleted while it holds any active membership — see clientGroupMembership and Client Groups API-A.

Audited fields

Recorded (created/deleted: full set; updated: changed fields only): name, maxClientCount.

Excluded:

• id, createdAt, updatedAt, deletedAt, createdBy, updatedBy — redundant with the audit entry's own entityId/createdAt/createdBy, which already identify the record and the write.

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.