106 lines
2.7 KiB
Markdown
106 lines
2.7 KiB
Markdown
|
# @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
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# 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.
|