Tag Groups

Overview

Tag groups are ICE Collections (IAO) — named groupings of Tag ICEs linked by the BFO member_part_of relation. Staff save these collections for repeated analytics queries. Instead of manually selecting the same set of tags each time, users create an ICE Collection (e.g., “Summer 2024 Collection”) and track its Measurement Data over time via tag analytics.

Goal: Enable reusable, named ICE Collections for consistent performance tracking.

Participants

Actor	Ontological type	Role
Staff user (Creative/Ops)	Person (CCO) bearing Role	Creates, edits, and deletes ICE Collections
Dashboard API Worker	EngineeredSystem (IOF)	Serves CRUD endpoints
PlanetScale	EngineeredSystem (IOF)	IBE store for ICE Collections

API endpoints

Method	Path	Description
GET	/api/tag-groups	List all ICE Collections
POST	/api/tag-groups	Create or update an ICE Collection (upsert by name)
DELETE	/api/tag-groups/:groupId	Delete an ICE Collection

Create/update request

// POST /api/tag-groups
{
  name: string,        // ICE Collection name, e.g. "Summer 2024 Collection"
  tagNames: string[]   // Tag ICE identifiers, e.g. ["summer-2024", "floral", "tropical"]
}

The endpoint upserts — if an ICE Collection with the same name already exists, it updates the member Tag ICEs.

Response DTO

interface InformationEntityCollection {
  id: string;          // UUID
  name: string;        // Collection name
  tagNames: string[];  // member_part_of Tag ICE identifiers
}

Database table

[IAO: ICE Collection | BFO: member_part_of relation to Tag ICEs]

Column	Type	Description
id	UUID	Primary key
name	VARCHAR(255)	ICE Collection name
tag_names	JSONB	Array of Tag ICE identifiers (member_part_of relation)
temporal_origin	TIMESTAMPTZ	Creation timestamp
last_modified_at	TIMESTAMPTZ	Last update timestamp

Relationship to tag analytics

ICE Collections feed into the tag analytics group performance endpoint:

GET /api/tag-analytics/group-performance/:groupId

This looks up the ICE Collection’s member Tag ICEs and runs the same aggregate Measurement Data query as the bulk performance endpoint.

Migration notes

The current system uses Supabase RPCs (upsert_tag_group, get_tag_groups, delete_tag_group). In the rewrite, these become straightforward Drizzle CRUD operations on the information_entity_collection table.

Acceptance criteria

• Creating an ICE Collection with a new name inserts a new record
• Creating an ICE Collection with an existing name updates the member Tag ICEs
• Deleting an ICE Collection removes it and its analytics no longer resolve
• ICE Collection performance via analytics endpoint returns correct aggregated Measurement Data