Skip to main content

CrimooCopilot-Backend

Purpose and Production Relevance​

CrimooCopilot-Backend is a standalone AI/GTM automation backend. It appears to be a separate Copilot service that can authenticate with Google, inspect GTM accounts/containers/workspaces, process chat requests with Gemini, generate plans, execute GTM configuration changes, and validate results.

Production relevance: supporting/parallel Copilot application. Confirm active deployment path before treating it as the source of truth, because the main node-api also documents integrated Copilot session routes.

Stack and Main Dependencies​

  • Express and TypeScript.
  • Google Gemini via @google/generative-ai.
  • Google APIs and OAuth libraries.
  • PostgreSQL via pg.
  • JWT and bcrypt.
  • Playwright for integration/DOM verification tests.

Important files and folders:

  • CrimooCopilot-Backend/src/application/flows
  • CrimooCopilot-Backend/src/application/services
  • CrimooCopilot-Backend/src/application/use-cases
  • CrimooCopilot-Backend/src/domain
  • CrimooCopilot-Backend/src/infrastructure
  • CrimooCopilot-Backend/src/tests

Business Responsibilities​

  • Authenticate users through Google OAuth.
  • List Google Tag Manager accounts, containers, and workspaces.
  • Accept chat messages and convert user intent into GTM automation plans.
  • Build tags, triggers, and variables.
  • Execute GTM changes through Google APIs.
  • Validate generated configurations semantically and, where possible, through DOM/browser checks.
  • Maintain learning/RAG-style prompt enhancement data.

Technical Architecture and Source-Code Entry Points​

Architecture is layered:

  • domain: entities, ports, catalog, and types.
  • application: flows, use cases, orchestration services, prompt builders, validators.
  • infrastructure: controllers, Google/Gemini adapters, repositories, builders, compilers, web middleware, and observability.

Core flow:

Key Data Flows and Service Integrations​

  • Google OAuth grants access to GTM APIs.
  • Gemini turns user intent into structured actions.
  • Builder classes produce GTM tag, trigger, and variable payloads.
  • Validators reduce invalid GTM changes before execution.
  • Playwright/DOM verification can validate site behavior after changes.

Environment, Deploy, and Runtime Notes​

Common commands:

cd CrimooCopilot-Backend
npm install
npm run dev
npm run build
npm run start
npm run test:all
npm run test:integration

Check .env or project docs before running because Google OAuth, Gemini, JWT, and database credentials are required.

Debugging Checklist​

  • If Google account/container lists fail, check OAuth token storage and scopes.
  • If Gemini responses are malformed, inspect prompt builder, response parser, and schema expectations.
  • If execution fails, inspect builder payloads and GTM API error translation.
  • If duplicate tags/triggers appear, inspect duplicate checker behavior.
  • If DOM verification fails, inspect Playwright target URL, auth state, and page selectors.

Tests or Validation Commands​

cd CrimooCopilot-Backend
npm run build
npm run test:all
npm run test:integration

Mastery Checklist​

  • Explain the difference between flow orchestration, builders, compilers, and Google API adapters.
  • Add a new automation flow with prompt support, validation, execution, and tests.
  • Debug a malformed Gemini response without bypassing validation.
  • Confirm whether a Copilot issue belongs here or in main node-api.