Skip to main content

agent

Purpose and Production Relevance​

agent is a Go worker-node service from an earlier or alternate distributed edge architecture. It manages GTM Docker containers, consumes tagging events, writes analytics, reports usage, and invalidates local router cache.

Production relevance: legacy/experimental or future-edge context. Existing internal docs identify gtm-fabric and gtm-proxy as the current production data-plane path.

Stack and Main Dependencies​

  • Go 1.23/1.24 toolchain.
  • Echo web framework.
  • Docker SDK.
  • Google Pub/Sub and Secret Manager.
  • PostgreSQL.
  • Redis.
  • ClickHouse.
  • Prometheus metrics.
  • GeoIP and user-agent parsing.

Important files and folders:

  • agent/cmd
  • agent/internal/application
  • agent/internal/core
  • agent/internal/infrastructure
  • agent/schema
  • agent/test
  • agent/go.mod

Business Responsibilities​

The agent overlaps with some current gtm-fabric responsibilities:

  • Deploy and manage GTM Docker containers.
  • Consume raw tagging events from Pub/Sub.
  • Parse and enrich events.
  • Store analytics in ClickHouse.
  • Report usage to node-api.
  • Invalidate local router/Redis cache after configuration changes.
  • Support preview mode by coordinating with a co-located router.

Technical Architecture and Source-Code Entry Points​

The project follows a Go clean-ish layering:

  • cmd: binary entry point.
  • internal/application: API/use-case layer.
  • internal/core: domain logic.
  • internal/infrastructure: Docker, Pub/Sub, database, Redis, metrics adapters.

Key Data Flows and Service Integrations​

Documented flow:

  1. Node API sends config/deploy commands over a secure network.
  2. Gateway/router receives browser traffic and publishes raw events.
  3. Agent consumes events from Pub/Sub.
  4. Agent forwards to GTM containers and writes ClickHouse analytics.
  5. Agent reports usage back to node-api.
  6. Agent invalidates router cache when local config changes.

Environment, Deploy, and Runtime Notes​

Common commands:

cd agent
go test ./...
go run cmd/agent/main.go
docker compose up --build

Runtime dependencies:

  • Docker socket.
  • Redis.
  • ClickHouse.
  • PostgreSQL.
  • Pub/Sub.
  • Internal API secret.

Debugging Checklist​

  • If containers do not deploy, check Docker socket permissions and network mode.
  • If Pub/Sub consumption fails, check subscription ID, credentials, and emulator/production config.
  • If analytics are missing, check ClickHouse connection and batch insert errors.
  • If router routes are stale, check Redis cache invalidation calls.
  • If behavior conflicts with current docs, prefer gtm-fabric/gtm-proxy as production truth.

Tests or Validation Commands​

cd agent
go test ./...

Mastery Checklist​

  • Explain how this architecture differs from current gtm-fabric/gtm-proxy.
  • Identify reusable ideas without assuming production ownership.
  • Run and test the Go service locally.