# @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.