Platform Telemetry Phase 3 & Architecture Rollout

Status: In Progress (Stories 3.1, 3.2 & dot-docs complete; Stories 3.3–3.5 pending app integration)
Last Updated: 2026-10-17
Epic Reference: DotEvolve/dot-docs#4
Related Issue: DotEvolve/govnix.net#32 (Configuration & Environment Standardization)

1. Executive Summary

Phase 1 established self-hosted Umami v2 on Oracle Cloud Infrastructure (OCI) compute with automated daily backups to Cloudflare R2 (dotevolve-analytics-backups). Phase 2 introduced the centralized telemetry SDK inside @dotevolve/error-utils (v1.0.24) providing cookieless tracking, universal script injection (initUmami), route tracking hooks (useUmamiPageTracking, usePageTracking), and Core Web Vitals monitoring.

Phase 3 executes the platform-wide integration across all 11 frontend properties and migrates the documentation site to Cloudflare Pages: 1. TypeScript 6 Standard Alignment: Standardized tsconfig.json across services by removing deprecated baseUrl: "." without using ignoreDeprecations: "6.0". 2. Repository Configuration Standardization: Committed authenticated .npmrc (${NPM_TOKEN}) across all 22 workspace repositories to unblock private package resolution on Cloudflare Pages and CI/CD pipelines (Issue #32). 3. Documentation Infrastructure Migration (dot-docs): Migrated public documentation (docs.dotevolve.net) from Vercel to Cloudflare Pages, provisioned a dedicated tracking ID, and embedded telemetry into MkDocs Material via theme overrides. 4. Application & Marketing Rollout: Embedded and validated telemetry across 3 public marketing websites and 7 internal single-page applications.

2. TypeScript 6 & Build Standardization

2.1 Problem & Deprecation

In TypeScript 6.0+, the baseUrl compiler option is deprecated (error TS5101: Option 'baseUrl' is deprecated and will stop functioning in TypeScript 7.0). In govnix-workflow-service, this triggered build failures during tsc.

2.2 Standardized Workspace Pattern

Following the pattern established in floorix-api: - Removed baseUrl: "." completely from tsconfig.json. - Avoided "ignoreDeprecations": "6.0": Workarounds using this compiler option were strictly rejected in both tsconfig.json and jest.config.js. - Prefixed Path Mappings: Updated compiler option paths with explicit relative paths:

"paths": {
  "@dotevolve/core/cache": ["./node_modules/@dotevolve/core/dist/cache"],
  "@dotevolve/core/logger": ["./node_modules/@dotevolve/core/dist/logger"],
  "@dotevolve/core/email": ["./node_modules/@dotevolve/core/dist/email"]
}

- Node16 Types Re-export: Added govnix-workflow-service/src/types.ts exporting * from "./types/index.js"; so Node16 module resolution resolves ../types.js imports without requiring directory-index fallback. - Cache Invalidation Signatures: Refactored cache invalidation middleware in api/routes/entities.ts, api/routes/workflowInstances.ts, and api/routes/userEntityAccess.ts to pass typed prefix functions returning string | null.

3. Repository Configuration & Environment Baseline (Issue #32)

To ensure smooth builds on Cloudflare Pages, Docker, and CI/CD without exposing secrets:

3.1 Authenticated `.npmrc`

All 22 workspace repositories have an authenticated .npmrc committed directly to remote git:

@dotevolve:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${NPM_TOKEN}
//npm.pkg.github.com/download/:_authToken=${NPM_TOKEN}
legacy-peer-deps=true

- The variable NPM_TOKEN is defined in Cloudflare Pages (under Settings → Environment variables) and in GitHub repository secrets. - .npmrc is unignored in all .gitignore files.

3.2 Environment Templates & Sanitization

Stale backup files (.env.*backup*, .env.bak, .env.tmp) have been completely removed.
All local configuration files (.env.dev.local, .env.prod.local, .env.test.local) are strictly git-ignored.

All 10 frontend .env.example templates standardize the telemetry keys:

# Platform Telemetry (Umami v2)
VITE_UMAMI_HOST_URL=https://analytics-dev.dotevolve.net
VITE_UMAMI_WEBSITE_ID=

# Marketing Analytics (GA4 - Production Only)
VITE_GA_MEASUREMENT_ID=

4. `dot-docs` Migration to Cloudflare Pages & Analytics Integration

4.1 Migration Overview

Previously configured for Vercel, the public documentation site at docs.dotevolve.net has been transitioned to Cloudflare Pages to consolidate hosting under Cloudflare and benefit from edge performance.

4.2 Build Specifications

Build Directory Root: /
Build Command: cd public && pip install -r requirements.txt && mkdocs build --clean
Build Output Directory: public/site
Python Version: 3.11 (configured via PYTHON_VERSION=3.11 in Cloudflare Pages)

Dependencies (public/requirements.txt):

mkdocs>=1.6.0
mkdocs-material>=9.5.0
pymdown-extensions>=10.7

4.3 Umami Telemetry Integration

Website ID (Dev): cf4ee4d5-e66c-4cbf-ab53-8a90b9bb0b32
Domain (Dev): docs-dev.dotevolve.net
Domain (Prod): docs.dotevolve.net

Injection Method: Implemented via Material for MkDocs theme override in dot-docs/public/overrides/main.html:

{% extends "base.html" %}

{% block analytics %}
  <script defer src="https://analytics-dev.dotevolve.net/script.js" data-website-id="cf4ee4d5-e66c-4cbf-ab53-8a90b9bb0b32"></script>
{% endblock %}

MkDocs Theme Config (public/mkdocs.yml):

theme:
  name: material
  custom_dir: overrides
  logo: assets/logo.png

5. Website Tracking Catalog Matrix

#	Application / Site	Repository	Dev Domain	Prod Domain	Dev `website_id`	Prod Env Variable
1	DotEvolve Docs	`dot-docs`	`docs-dev.dotevolve.net`	`docs.dotevolve.net`	`cf4ee4d5-e66c-4cbf-ab53-8a90b9bb0b32`	`VITE_UMAMI_WEBSITE_ID_DOT_DOCS`
2	DotEvolve Marketing	`dotevolve.net`	`dev.dotevolve.net`	`dotevolve.net`	`4db51fde-6361-4573-8016-b63a47f2d71a`	`VITE_UMAMI_WEBSITE_ID_DOTEVOLVE`
3	Floorix Marketing	`floorix.net`	`dev.floorix.net`	`floorix.net`	`cb383e39-7c23-414c-b670-373794f1d218`	`VITE_UMAMI_WEBSITE_ID_FLOORIX_NET`
4	Govnix Marketing	`govnix.net`	`dev.govnix.net`	`govnix.net`	`5c332ad5-0b43-41c2-994b-57974d10878f`	`VITE_UMAMI_WEBSITE_ID_GOVNIX_NET`
5	Perfxcel Marketing	`perfxcel-app`	`dev.perfxcel.com`	`perfxcel.com`	`eb7bf633-d1e2-4890-bd2f-f3a2f938e62a`	`VITE_UMAMI_WEBSITE_ID_PERFXCEL_NET`
6	Dot Portal	`dot-portal`	`portal-dev.dotevolve.net`	`portal.dotevolve.net`	`e19e44a5-7e5e-4b32-85c5-a60be1a59f8a`	`VITE_UMAMI_WEBSITE_ID_DOT_PORTAL`
7	Govnix App	`govnix-app`	`app-dev.govnix.net`	`app.govnix.net`	`db563bc1-97ff-4151-a90e-5cb35ab45b5d`	`VITE_UMAMI_WEBSITE_ID_GOVNIX_APP`
8	Govnix Admin	`govnix-admin`	`admin-dev.govnix.net`	`admin.govnix.net`	`f935e355-3a26-442f-bc3d-da4b748ddeca`	`VITE_UMAMI_WEBSITE_ID_GOVNIX_ADMIN`
9	Floorix App	`floorix-app`	`app-dev.floorix.net`	`app.floorix.net`	`b7e260f7-67f5-4f7e-93db-75c286aa6e54`	`VITE_UMAMI_WEBSITE_ID_FLOORIX_APP`
10	Floorix Admin	`floorix-admin`	`admin-dev.floorix.net`	`admin.floorix.net`	`e2368547-4caf-4ef7-8331-ef8e267e3aa2`	`VITE_UMAMI_WEBSITE_ID_FLOORIX_ADMIN`
11	Perfxcel Admin	`perfxcel-admin`	`admin-dev.perfxcel.com`	`admin.perfxcel.com`	`adddd066-ad94-46d5-9b0f-86dece904c81`	`VITE_UMAMI_WEBSITE_ID_PERFXCEL_ADMIN`

6. Implementation Stories & Progress Status

Story	Scope	Primary Repositories	Status
3.1	Cloud Build Auth (`.npmrc`) & Configuration Baseline (Issue #32)	All 22 repositories	Completed
3.2	Marketing Websites Telemetry Verification	`govnix.net`, `floorix.net`, `dotevolve.net`	Completed
3.2b	`dot-docs` Migration to Cloudflare Pages & Umami Injection	`dot-docs`, `dot-infra`	Completed
3.3	Internal Apps Integration (Govnix, Portal, Floorix, Perfxcel)	7 internal SPAs	In Progress
3.4	Domain Event & Funnel Tracking	Internal SPAs	Pending
3.5	Dashboard Funnels & Production Cutover Runbook	Umami UI, `dot-docs`	Pending