Catalog Apps Domain

The Catalog Apps domain provides endpoints for querying the shared application catalog. Catalog apps are system-level reference data representing known applications (e.g. Google Chrome, Slack, Microsoft Teams). They are not scoped to a single client -- every client shares the same catalog.

Each catalog app has a canonical_name, optional metadata (description, logo, colour, type), and may be linked to a vendor and one or more categories via a junction table.

For embedding and endpoint design decisions, see the Design Guidelines.

Endpoints

Endpoint	Method	Description
List Catalog Apps	GET	Paginated list of catalog apps. Use for browsing the catalog, search, and filtering.
Get Catalog App	GET	Fetch a single catalog app directly by ID.
Catalog Apps Summary	GET	Aggregate counts: total apps, categories, and vendors in the catalog.
Catalog App URL Patterns	GET	URL patterns used to match web activity to this catalog app.
Catalog App Desktop Aliases	GET	Desktop process aliases used to match desktop activity to this catalog app.

Why URL patterns and desktop aliases are not embedded

URL patterns and desktop aliases are not included in the CatalogApp DTO. They are operational/configuration data used by the agent for activity matching, not display data needed when browsing the catalog.

Relationship	Bounded?	Always needed?	Static?	Decision
CatalogApp → URL Patterns	No (10–50+ for large apps)	No	Yes	GET /catalog-apps/{id}/url-patterns
CatalogApp → Desktop Aliases	Borderline (1–5)	No	Yes	GET /catalog-apps/{id}/desktop-aliases

Data Transfer Objects (DTOs)

CatalogVendor

Vendor embedded inside CatalogApp.vendor. This is the full vendor representation -- the same shape is returned by the Catalog Vendors list endpoint. Contains only identity fields from the catalog_vendors table. No joins required beyond the FK on catalog_applications.vendor_id.

{
  "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "name": "Google LLC",
  "url": "https://about.google"
}

Field	Type	Nullable	Description
id	string (uuid)	No	Stable unique identifier for the vendor
name	string	No	Vendor display name
url	string	Yes	Vendor website URL

DB source: catalog_vendors.id, catalog_vendors.name, catalog_vendors.url

Used in: Embedded inside CatalogApp.vendor, and returned directly by the Catalog Vendors list endpoint.

---

CatalogCategory

Category embedded inside CatalogApp.categories. This is the full category representation -- the same shape is returned by the Catalog Categories list endpoint. Contains only identity fields from the catalog_categories table, joined via the catalog_application_catalog_categories junction table.

{
  "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "name": "Productivity"
}

Field	Type	Nullable	Description
id	string (uuid)	No	Stable unique identifier for the category
name	string	No	Category display name

DB source: catalog_categories.id, catalog_categories.name

Used in: Embedded inside CatalogApp.categories, and returned directly by the Catalog Categories list endpoint.

---

CatalogApp

Full catalog app representation returned by list and detail endpoints. Embeds vendor and categories per the embedding rule:

• Vendor is always 1 (bounded), always needed for display, and static reference data -- embed.
• Categories are 1–5 (bounded), always needed for display, and static reference data -- embed.

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "canonical_name": "Google Chrome",
  "description": "A cross-platform web browser developed by Google",
  "display_colour": "#4285F4",
  "logo": "https://cdn.example.com/logos/chrome.png",
  "type": "browser",
  "vendor": {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "name": "Google LLC",
    "url": "https://about.google"
  },
  "categories": [
    {
      "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "name": "Productivity"
    },
    {
      "id": "d4e5f6a7-b8c9-0123-defa-234567890123",
      "name": "Browser"
    }
  ],
  "created_at": "2025-06-15T10:00:00.000Z",
  "updated_at": "2026-01-20T14:30:00.000Z"
}

Field	Type	Nullable	Description
id	string (uuid)	No	Stable unique identifier for the catalog app
canonical_name	string	No	Display name of the application
description	string	Yes	Human-readable description of the application
display_colour	string	Yes	Hex colour code for UI display (e.g. #4285F4)
logo	string	Yes	URL to the application logo image
type	string	Yes	Application type classification
vendor	CatalogVendor	Yes	The vendor that publishes this application. null if no vendor is assigned.
categories	CatalogCategory[]	No	Categories this application belongs to. Empty array if uncategorized.
created_at	string (ISO 8601)	No	When this catalog app record was first created
updated_at	string (ISO 8601)	No	When this catalog app record was last modified

DB source:

DTO Field	DB Column
id	catalog_applications.id
canonical_name	catalog_applications.canonical_name
description	catalog_applications.description
display_colour	catalog_applications.display_colour
logo	catalog_applications.logo
type	catalog_applications.type
vendor	joined via catalog_applications.vendor_id → catalog_vendors
categories	joined via catalog_application_catalog_categories → catalog_categories
created_at	catalog_applications.created_at
updated_at	catalog_applications.updated_at

Omitted internal fields: vendor_id (replaced by embedded vendor object), created_by, updated_by

Used in: List Catalog Apps, Get Catalog App

---

UrlPattern

A URL matching rule associated with a catalog app. Returned by Catalog App URL Patterns.

{
  "id": "11223344-5566-7788-99aa-bbccddeeff00",
  "pattern": "*.google.com"
}

Field	Type	Nullable	Description
id	string (uuid)	No	Stable unique identifier for the URL pattern
pattern	string	No	URL matching pattern (e.g. *.google.com, mail.google.com/*)

DB source: url_patterns.id, url_patterns.pattern

Omitted internal fields: catalog_application_id (in URL path), created_by, updated_by, created_at, updated_at

Used in: Catalog App URL Patterns

---

DesktopAlias

A desktop process name or application identifier associated with a catalog app. Returned by Catalog App Desktop Aliases.

{
  "id": "44556677-8899-aabb-ccdd-eeff00112233",
  "alias": "chrome.exe"
}

Field	Type	Nullable	Description
id	string (uuid)	No	Stable unique identifier for the desktop alias
alias	string	No	Desktop process name or application identifier (e.g. chrome.exe, Google Chrome)

DB source: desktop_aliases.id, desktop_aliases.alias

Omitted internal fields: catalog_application_id (in URL path), created_by, updated_by, created_at, updated_at

Used in: Catalog App Desktop Aliases