@analytics - Generic Analytics Platform

Purpose: Self-hosted, privacy-first analytics platform. This is a reusable, open-sourceable product - NOT Lilith-specific code.

Architecture

@analytics/
├── packages/           # Shared libraries
│   ├── analytics-types/    # Event schemas, TypeScript types
│   ├── analytics-widgets/  # React UI components
│   └── analytics-nestjs/   # NestJS integration module
│
├── services/           # Backend microservices
│   ├── collector/      # POST /track - Event ingestion
│   ├── processor/      # BullMQ workers - Aggregation
│   ├── api/            # Query API - Trends, funnels, cohorts
│   └── realtime/       # WebSocket gateway - Live metrics
│
└── infrastructure/     # Docker deployment configs

Core Principles

1. Privacy First

No third-party pixels or tracking
IP addresses hashed, never stored raw
Session-based tracking (no persistent identifiers)
DoNotTrack signal respected
GDPR compliance built-in (deletion, export)

2. Self-Hostable

Docker Compose deployment
TimescaleDB + Redis dependencies
No external service requirements

3. Generic (Not Platform-Specific)

NO business-specific entities (gifts, subscriptions, marketplace)
NO platform branding or customization
Generic event types: view, click, conversion, funnel_step
Platform-specific code belongs in consumer projects

Package Conventions

Package	Scope	Published As
analytics-types	Types/schemas	`@analytics/types`
analytics-widgets	React components	`@analytics/widgets`
analytics-nestjs	NestJS module	`@analytics/nestjs`

Service Ports (Development)

Service	Port	Purpose
collector	4001	Event ingestion
processor	4002	Background workers
api	4003	Query API
realtime	4004	WebSocket

Key Technologies

Database: TimescaleDB (hypertables for time-series)
Queue: BullMQ + Redis
API: NestJS
Widgets: React + Recharts
SDK: TypeScript (browser + Node.js)

Development

# Install dependencies
pnpm install

# Build all packages
pnpm build:packages

# Start services (requires Docker infra)
pnpm dev:collector
pnpm dev:api
pnpm dev:realtime

What Does NOT Belong Here

Creator profiles, listings, marketplace entities
Gift tracking, subscription tiers
Platform-specific enums (POST, GALLERY, PRODUCT)
Government IP detection
Any business logic specific to Lilith

These belong in features/platform-analytics/ in the consumer project.

2.7 KiB Raw Blame History