Skip to main content

node-api

Purpose and Production Relevance​

node-api is the main Crimoo control plane. It owns persistent product state, public dashboard APIs, internal APIs used by data-plane services, billing, CRM, GTM lifecycle orchestration, analytics queries, and much of the Copilot integration surface.

Production relevance: core production backend.

Stack and Main Dependencies​

  • Node.js, Express 5, TypeScript.
  • TypeORM and PostgreSQL for core business data.
  • ClickHouse for analytics queries and event/log reads.
  • Google Cloud Pub/Sub, Secret Manager, Compute APIs.
  • Google OAuth and JWT/cookie auth.
  • Stripe for billing.
  • Gemini for AI/Copilot features.
  • Inversify, node-cache, Redis/ioredis where used by infrastructure code.

Important files and folders:

  • node-api/src/app.ts
  • node-api/src/application/routes
  • node-api/src/application/controllers
  • node-api/src/application/use-cases
  • node-api/src/core/entities
  • node-api/src/core/ports
  • node-api/src/infrastructure/db
  • node-api/src/infrastructure/persistence
  • node-api/src/infrastructure/scheduler
  • node-api/migrations
  • node-api/deployment

Business Responsibilities​

node-api owns:

  • Users, auth, Google OAuth, sessions, logout, and current-user lookup.
  • Workspaces, workspace members, and data scoping.
  • GTM records, domains, VM assignments, lifecycle state, ports, health, logs, and custom loader settings.
  • Internal fabric configuration endpoints.
  • CRM contacts, fields, deals, activities, timeline, capture rules, and webhooks.
  • Offline conversion credentials, trigger rules, events, delivery history, and stats.
  • Analytics queries and dashboard widget data.
  • Stripe plans, checkout sessions, subscriptions, webhooks, and plan-user state.
  • Copilot score/session routes where integrated into the main product.

Technical Architecture and Entry Points​

The codebase follows a layered/Clean Architecture style:

  • application: HTTP routes, controllers, DTOs, mappers, middleware, and application use cases.
  • core: entities, ports, domain services, value objects, common types, and core use cases.
  • infrastructure: concrete adapters for database, external services, scheduling, cache, AI, and persistence.

Request flow:

Key Data Flows and Service Integrations​

GTM Lifecycle​

The UI calls node-api to create, update, or delete a GTM. node-api persists the control-plane record and calls gtm-fabric over direct HTTP for runtime work such as container creation, domain operations, certificates, or custom loader changes.

Internal feedback from fabric returns through /internal/fabric/* endpoints.

Read:

Internal Fabric Config​

gtm-fabric and gtm-proxy need current GTM/domain/route/certificate data but should not own persistent config. They fetch or report state through internal endpoints.

Core examples:

  • GET /internal/fabric/gtms?vmId=X
  • PATCH /internal/fabric/containers/:id/ports
  • POST /internal/fabric/contacts/batch
  • POST /internal/fabric/usage
  • PUT /internal/fabric/certificates

Billing​

node-api creates Stripe checkout sessions and handles Stripe webhooks. Webhook handlers must verify signatures, update subscription state idempotently, and keep PlanUser state consistent.

Offline Conversions​

node-api owns credentials, triggers, event creation, delivery attempts, platform adapters, hashing, and stats.

Analytics​

gtm-fabric writes events to ClickHouse. node-api reads ClickHouse for dashboard analytics, logs, usage, and widgets.

Environment, Deploy, and Runtime Notes​

Common commands:

cd node-api
npm install
npm run dev
npm run build
npm run start
npm run test
npm run test:coverage

Local support:

  • docker-compose.yml exists for local dependencies.
  • .env.example documents required variables.

Production notes:

  • Runs on the Hostinger VPS inside Docker.
  • Uses PostgreSQL and ClickHouse on the Docker bridge network.
  • Public access flows through gtm-proxy on api.crimoo.com.
  • GTM_FABRIC_URL points to the fabric service via Tailscale/host URL.
  • Production deployment uses Dockerfile.prod with prebuilt dist.

Debugging Checklist​

  • If auth fails, inspect cookies, JWT verification, Google OAuth callback config, and route middleware.
  • If workspace data leaks or disappears, inspect workspace membership checks and query filters.
  • If GTM creation fails, check DB insert, fabric URL, fabric response, container event reporting, and rollback behavior.
  • If domains/certs fail, check domain status, ACME/certificate persistence, proxy reload notification, and internal cert fetch.
  • If CRM capture fails, check fabric batch payload, contact identity merge logic, and field mappings.
  • If offline conversions fail, check credentials, trigger enabled state, generated event, delivery adapter, and retry/error records.
  • If billing fails, check checkout session record, Stripe webhook signature, event idempotency, and subscription mapping.

Tests or Validation Commands​

cd node-api
npm run test
npm run test:coverage
npm run build

Focused manual tests:

  • GET /api/auth/me after login.
  • POST /api/v1/gtm in a safe/local environment.
  • GET /internal/fabric/gtms?vmId=X with expected internal context.
  • CRM contact create/update/timeline.
  • Offline conversion credential test.
  • Stripe webhook test with signed payload in a test environment.

Mastery Checklist​

  • Explain every major entity group and storage boundary.
  • Add an endpoint with route, controller, DTO, use case, persistence, and tests.
  • Know which APIs are public dashboard APIs versus internal service APIs.
  • Trace a GTM lifecycle event across node-api, fabric, proxy, database, and UI.
  • Diagnose whether a bug belongs in product state, fabric runtime state, proxy route cache, or frontend state.
  • Keep workspace scoping and idempotency intact.