digital-identity-platform-docs

---

digital-identity-platform-docs / supabase/functions/sgtm-containers

supabase/functions/sgtm-containers

Fileoverview

SGTM Containers Edge Function

Manages Server-side Google Tag Manager container lifecycle including creation, infrastructure provisioning, and verification.

Cloudflare Architecture Context

Attribute	Value
Classification	🟡 TRANSITIONAL
Position	App Backend (orchestrates provisioning)
Receives Public Traffic	No (dashboard only)
Latency Sensitive	No (async provisioning)
Safe to Retry	No (creates resources)
Failure Behavior	Partial rollback on infra failure

⚠️ TRANSITION NOTE

This function currently handles both:

1. Container creation with infrastructure provisioning
2. Container verification via Cloudflare Worker

Planned Consolidation: Consider merging with provision_sgtm_container to reduce code duplication. Both functions share port allocation, hostname generation, and infra provisioning logic.

What Would Break if Removed:

• Container creation from Dashboard
• Container verification flow
• Initial site and site_domains creation

Endpoint

POST /sgtm-containers - Create a new container with infrastructure

Endpoint

POST /sgtm-containers/:id/verify - Re-verify an existing container

Auth

Required - JWT in Authorization header

Remarks

This is the main orchestration function for container management:

Create Flow (POST /sgtm-containers):

1. Validates user permissions (admin/owner role required)
2. Parses and validates GTM container configuration
3. Creates container record in database
4. Allocates ports from port_pool
5. Calls Infrastructure Provisioner to set up Caddy, DNS, etc.
6. Creates site and site_domains records for each domain

Verify Flow (POST /sgtm-containers/:id/verify):

1. Fetches existing container
2. Validates user permissions
3. Calls Cloudflare Worker to verify GTM configuration
4. Updates container status based on verification result

Tables touched:

• sgtm_containers (read/write)
• client_memberships (read)
• port_pool (read/write via admin client)
• sites (write)
• site_domains (write)
• clients (read)

External services:

• Infrastructure Provisioner (INFRA_PROVISIONER_URL)
• Cloudflare GTM Worker (CLOUDFLARE_GTM_WORKER_URL)

Example

{
  "clientId": "uuid",
  "name": "My Container",
  "domains": ["example.com", "shop.example.com"],
  "webGtmIds": { "example.com": "GTM-XXXX" },
  "containerConfigB64": "base64-encoded-config"
}

Interfaces

• ContainerConfig
• CreateContainerRequest
• CreateContainerResponse
• VerifyContainerResponse