Tracking System V1 - Mobsuccess LCM

User behavior tracking system built from scratch for the Mobsuccess frontend monorepo. Tracks page views, clicks, and custom events from internal users.

Architecture

tracking-system/
├── backend/ # AWS Amplify Gen 2 backend
│ └── functions/tracking/
│ ├── schema.ts # DynamoDB models + GraphQL mutation
│ ├── resource.ts # Lambda function definition
│ └── handler.ts # Ingestion handler (batch events)
├── frontend/ # React hooks (goes in react-shared)
│ ├── hooks/
│ │ ├── use-track.ts # useTrack() hook for custom events
│ │ └── use-track-types.ts # TypeScript types
│ └── provider/
│ └── use-track-provider.tsx # TrackingProvider (auto-tracking)
├── dashboard/ # Standalone webapp
│ └── src/
│ ├── routes/v1/ # Pages: overview, events, users, pages
│ ├── views/app-layout/ # Layout with sidebar
│ └── features/api/ # AppSync queries
└── integration/ # Patches to apply on the monorepo
├── lcm-root.tsx.patch # Wrap LCM with TrackingProvider
├── data-resource.patch # Register schema in AppSync
├── backend.patch # Register Lambda in backend.ts
└── hooks-index.patch # Export hooks from react-shared

How It Works

Automatic Tracking (zero-config for developers)

The TrackingProvider automatically captures:

• Page views: Listens to TanStack Router route changes (router.subscribe('onResolved'))
• Clicks: Event delegation on document capturing clicks on elements with data-tracking-id (already enforced by ESLint on all interactive components)

Custom Events

import{useTrack}from"@mobsuccess-devops/react-shared/hooks";functionMyComponent(){const{ track }=useTrack();consthandleCreate=useCallback(()=>{// ... business logictrack({name: "campaign.created",metadata: {campaignId: "xxx"}});},[track]);return<ButtononClick={handleCreate}>Create</Button>;}

Batching

Events are buffered and sent in batches:

• Every 10 seconds (configurable via flushIntervalMs)
• When buffer reaches 20 events (configurable via maxBatchSize)
• On page unload via navigator.sendBeacon

User Context

Each event is enriched with workspace context from useWorkspace():

• userId, userEmail, userName
• agencyUuid, advertiserUuid, accountId
• entrypoint (LCM, LCO, etc.)
• userAgent, screenWidth, screenHeight

Data Models

TrackingSession

Field	Type	Description
id	string (PK)	Session UUID
userId	string (GSI)	User ID
userEmail	string	User email
userName	string	Full name
agencyUuid	string	Current agency
advertiserUuid	string	Current advertiser
entrypoint	string	App name (LCM, LCO...)
userAgent	string	Browser user agent
screenWidth/Height	int	Screen dimensions
startedAt	datetime	Session start
lastActivityAt	datetime	Last event time

TrackingEvent

Field	Type	Description
id	string (PK)	Event UUID
sessionId	string (GSI)	Session reference
userId	string (GSI)	User ID
type	enum	page_view, click, custom
name	string	tracking-id / route / custom name
page	string	Current URL path
metadata	JSON	Custom event data
timestamp	datetime	Event time

Integration Steps

1. Backend

Copy backend/functions/tracking/ into backend/amplify/functions/tracking/ then apply patches from integration/:

• Register schema in backend/amplify/data/resource.ts
• Register function in backend/amplify/backend.ts

2. Frontend Hook

Copy frontend/ files into packages/react-shared/src/public/hooks/ then export from the hooks index.

3. LCM Integration

Wrap the LCM root layout with <TrackingProvider entrypoint="LCM">.

4. Dashboard

Copy dashboard/ as webapps/tracking-dashboard/ and run pnpm install.

Development

# Deploy backend sandbox
pnpm dev backend
# Start LCM (with tracking)
pnpm dev lcm
# Start tracking dashboard
pnpm dev tracking-dashboard

Roadmap

• V2: Dashboard enhancements (date range filters, charts, export)
• V3: Heatmaps (click position tracking + canvas overlay rendering)
• V4: Custom events API for developers, data retention policies

Tech Stack

• Backend: AWS Amplify Gen 2, DynamoDB, AppSync GraphQL, Lambda
• Frontend: React 18+, TypeScript, TanStack Router/Query
• Styling: PandaCSS
• UI: @mobsuccess-devops/react-ui (ArkUI-based design system)