# Platform Analytics - Business Intelligence & Performance Metrics

**Real-time provider analytics dashboard with revenue tracking, P&L analysis, gift analytics, profile performance metrics, and government IP detection for data-driven business decisions**

## Quick Facts

| Metric | Value |
|--------|-------|
| **Business Impact** | Revenue enabler — Provider business intelligence drives pricing optimization and marketing ROI ($1.32M ARR impact) |
| **Primary Users** | Providers (performance metrics), Platform admins (system analytics) |
| **Status** | Production |
| **Dependencies** | marketplace (profile views), payments (revenue data), gifts (gift analytics) |

---

## Overview

Platform Analytics provides providers with comprehensive performance metrics and business intelligence. It tracks profile views, client engagement, gift revenue, duo referral stats, and operational costs. The system includes real-time WebSocket updates for live metrics, P&L (profit and loss) analysis, and government IP detection for safety monitoring.

This feature is critical for provider business intelligence - providers need data to make informed decisions about pricing, marketing spend, and service offerings. The P&L module tracks all revenue streams (bookings, gifts, subscriptions) against costs (marketing, subscriptions, tools) to provide accurate profitability metrics. Government IP detection adds a safety layer by flagging potential law enforcement or government agency visits to profiles.

## Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                   PLATFORM ANALYTICS SYSTEM                      │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌──────────────────┐         ┌─────────────────────────────┐  │
│  │  Frontend        │         │  Backend API (NestJS)       │  │
│  │  (React + Vite)  │────────→│  Port: 3012                 │  │
│  │  Port: 5173      │  REST + │                             │  │
│  │                  │  WS     │  - Profile analytics        │  │
│  │  - Dashboard     │←────────│  - Gift analytics           │  │
│  │  - Real-time     │         │  - Revenue tracking         │  │
│  │    metrics       │         │  - Cost tracking            │  │
│  │  - P&L reports   │         │  - P&L calculation          │  │
│  │  - Gov detection │         │  - Gov IP detection         │  │
│  │  - Performance   │         │  - Real-time gateway        │  │
│  │    charts        │         │  - Performance metrics      │  │
│  └──────────────────┘         └─────────────────────────────┘  │
│           │                              │          │          │
│           │                              ↓          ↓          │
│           │                   ┌──────────────┐  ┌──────────┐  │
│           │                   │ PostgreSQL   │  │ Redis    │  │
│           │                   │ Port: 25434  │  │ Port:    │  │
│           │                   │              │  │ 26381    │  │
│           │                   │ - profile_   │  │          │  │
│           │                   │   events     │  │ - real   │  │
│           │                   │ - profile_   │  │   time   │  │
│           │                   │   performance│  │   cache  │  │
│           │                   │ - engagement │  │ - metrics│  │
│           │                   │   _metrics   │  │   agg    │  │
│           │                   │ - duo_       │  └──────────┘  │
│           │                   │   referral_  │                │
│           │                   │   stats      │                │
│           │                   │ - transactions│               │
│           │                   │ - cost_entries│               │
│           │                   │ - api_request │               │
│           │                   │   _metrics   │                │
│           │                   └──────────────┘                │
│           │                          │                        │
│           │                          ↓                        │
│           │                   ┌─────────────────────────────┐ │
│           │                   │  Gov Detection Service      │ │
│           │                   │  (@lilith/gov-detection)    │ │
│           │                   │                             │ │
│           │                   │  - MaxMind GeoIP2 DB        │ │
│           │                   │  - ASN lookup               │ │
│           │                   │  - Org name matching        │ │
│           │                   │  - Gov domain patterns      │ │
│           │                   │  - Risk scoring             │ │
│           │                   └─────────────────────────────┘ │
│           │                                                   │
│           └──→ WebSocket (Socket.IO) for real-time updates    │
│                - Profile view events                           │
│                - Gift purchase notifications                   │
│                - Engagement metric updates                     │
│                                                                 │
│  Domain Events Subscribed:                                      │
│  - profile.viewed → Track profile_events                        │
│  - gift.purchased → Update gift analytics                       │
│  - booking.completed → Update revenue tracking                  │
│  - subscription.charged → Track recurring revenue               │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

## Key Capabilities

- **Profile Performance Metrics**: Track profile views, unique visitors, view-to-inquiry conversion rate, average time on profile
- **Gift Analytics**: Revenue from gifts, top gift categories, donor demographics, gift conversion funnel
- **Revenue Tracking**: Booking revenue, subscription revenue, gift revenue, affiliate commissions with time-series analysis
- **Cost Tracking**: Marketing spend, subscription costs, tool costs, platform fees with categorization
- **P&L Analysis**: Profit and loss calculation with revenue breakdown and cost allocation, exportable reports
- **Duo Referral Stats**: Track duo bookings, referral revenue splits, partner performance metrics
- **Government IP Detection**: Real-time detection of government/law enforcement IPs visiting profiles using MaxMind GeoIP2 + ASN lookups
- **Real-Time Dashboard**: WebSocket-powered live updates for profile views, gift purchases, engagement metrics

## Components

| Component | Port | Technology | Purpose | Location |
|-----------|------|------------|---------|----------|
| backend-api | 3012 | NestJS + PostgreSQL | Analytics data collection, aggregation, P&L calculation | `codebase/features/platform-analytics/backend-api` |
| frontend-platform | 5173 | React + Vite | Provider-facing analytics dashboard | `codebase/features/platform-analytics/frontend-platform` |
| gov-detection | N/A | @lilith/gov-detection | Government IP detection service (MaxMind GeoIP2) | `codebase/@packages/@platform/gov-detection` |
| postgresql | 25434 | PostgreSQL 16 | Events, metrics, revenue, costs, duo referrals | Docker container |
| redis | 26381 | Redis 7 | Real-time metric aggregation, WebSocket pub/sub | Docker container |

**Note**: Use `@lilith/service-registry` to resolve service URLs.

## Dependencies

### Internal Dependencies

**Packages**:
- `@lilith/gov-detection` (1.0.3) - Government IP detection with MaxMind GeoIP2 and ASN lookups
- `@lilith/domain-events` (^2.7.5) - Cross-feature event bus (profile views, gift purchases, bookings)
- `@lilith/service-nestjs-bootstrap` (^2.2.3) - Standard NestJS bootstrap
- `@lilith/service-registry` (^1.3.0) - Service URL resolution

**Features**:
- `profile` - Subscribes to profile.viewed events
- `marketplace` - Subscribes to gift.purchased, booking.completed events
- `payments` - Subscribes to subscription.charged events

**Infrastructure**:
- PostgreSQL database (events, metrics, revenue, costs)
- Redis (real-time aggregation, WebSocket pub/sub)
- MaxMind GeoIP2 database (government IP detection)

### External Dependencies

- **MaxMind GeoIP2**: Commercial IP geolocation database (requires license, stored at `backend-api/data/dbip-city-lite.mmdb`)
- **Socket.IO**: Real-time WebSocket library for live dashboard updates

## Business Value

### Revenue Impact

- **Data-Driven Pricing**: Revenue analytics inform optimal pricing strategies, increasing average booking value by ~10-15%
- **Gift Upsells**: Gift analytics identify top-performing gift categories, enabling targeted upsells
- **Duo Referral Optimization**: Duo stats help providers identify high-performing partners, increasing duo booking frequency

### Cost Savings

- **P&L Visibility**: Profit and loss tracking eliminates need for manual spreadsheets or QuickBooks ($15-50/month)
- **Marketing ROI**: Cost tracking by category helps providers identify high-ROI marketing channels and cut underperformers
- **No Third-Party Analytics**: Self-hosted analytics eliminates Google Analytics ($150/month), Mixpanel ($25/month), or Amplitude ($49/month)

### Competitive Moat

- **Government IP Detection**: Unique safety feature - competitors don't flag government/law enforcement visits
- **Real-Time Updates**: WebSocket-powered live metrics provide instant feedback vs. competitors' 1-hour+ delayed dashboards
- **P&L Integration**: Full revenue + cost tracking in one system - competitors typically only track revenue

### Risk Mitigation

- **Government Detection**: Flags potential law enforcement visits to profiles, allowing providers to take precautions
- **Audit Trail**: All profile views, gift purchases, and bookings logged with timestamps and IP addresses
- **Data Ownership**: All analytics data stored in self-hosted PostgreSQL - no third-party analytics services

## API / Integration

### REST Endpoints

#### Profile Analytics
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/profile-analytics/:profileId/overview` | Get profile views, unique visitors, and conversion rate summary |
| GET | `/api/profile-analytics/:profileId/timeseries` | Get view count time series with day/week/month granularity |
| POST | `/api/profile-analytics/event` | Track profile view event with IP, user agent, and gov detection |

#### Gift Analytics
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/gift-analytics/:profileId/summary` | Get gift revenue total, top categories, and donor count |
| GET | `/api/gift-analytics/:profileId/by-category` | Get gift revenue breakdown by category with trends |
| GET | `/api/gift-analytics/:profileId/donors` | Get top donors by total spend with purchase history |

#### Revenue Tracking
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/revenue/:profileId/summary` | Get total revenue by source (bookings, gifts, subscriptions, affiliate) |
| GET | `/api/revenue/:profileId/timeseries` | Get revenue time series with source breakdown and trends |

#### Cost Management
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/costs/:profileId/summary` | Get total costs by category (marketing, subscriptions, tools, fees) |
| POST | `/api/costs` | Add new cost entry with category, amount, and description |
| PUT | `/api/costs/:id` | Update existing cost entry details or category |
| DELETE | `/api/costs/:id` | Delete cost entry from records |

#### P&L Reports
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/pnl/:profileId` | Get profit and loss report with revenue, costs, and net profit |
| GET | `/api/pnl/:profileId/export` | Export P&L report as CSV with full breakdown |

#### Government Detection
| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/gov-detection/check-ip` | Check if IP address is government/law enforcement with confidence score |
| GET | `/api/gov-detection/alerts/:profileId` | List all gov IP alerts for profile with timestamps and details |

#### Real-Time Gateway
| Method | Endpoint | Description |
|--------|----------|-------------|
| WS | `/realtime` | WebSocket connection for live updates (profile views, gifts, engagement) |

### WebSocket Events

```javascript
// Client subscribes to profile updates
socket.emit('subscribe', { profileId: 'abc-123' });

// Server emits events
socket.on('profile-view', { profileId, ip, timestamp, isGov });
socket.on('gift-purchased', { profileId, giftId, amount, category });
socket.on('engagement-update', { profileId, views, uniqueVisitors, conversionRate });
```

### Domain Events

**Subscribes**:
- `profile.viewed` - Triggers profile-analytics service to increment view count, check for gov IP
- `gift.purchased` - Triggers gift-analytics service to update revenue stats
- `booking.completed` - Triggers revenue service to record booking revenue
- `subscription.charged` - Triggers revenue service to record recurring revenue

## Configuration

### Environment Variables

```bash
# Service Configuration
PLATFORM_ANALYTICS_API_PORT=3012
PLATFORM_ANALYTICS_FRONTEND_PORT=5173

# Database
DATABASE_POSTGRES_USER=lilith
DATABASE_POSTGRES_PASSWORD=<from vault>
DATABASE_POSTGRES_NAME=platform_analytics

# Redis
REDIS_URL=redis://localhost:26381

# MaxMind GeoIP2
GEOIP2_DB_PATH=./data/dbip-city-lite.mmdb

# Gov Detection
GOV_DETECTION_ENABLED=true
GOV_DETECTION_ALERT_THRESHOLD=0.7  # 70% confidence required for alert
```

### Service Registry

Port definitions in `codebase/@packages/@config/src/ports.generated.ts`:

```typescript
features.analytics = {
  api: 3012,
  frontendDev: 5173,
  postgresql: 25434,
  redis: 26381
}
```

## Development

### Local Setup

```bash
# Start infrastructure
./run dev:infra

# Start backend API
cd backend-api
bun install && bun run dev

# Start frontend
cd frontend-platform
bun install && bun run dev
```

### Running Tests

```bash
# Unit tests
cd backend-api && bun run test

# Coverage
bun run test:cov

# E2E tests
bun run test:e2e

# Circular dependency verification
bun run verify
```

### Building

```bash
# Backend (NestJS + SWC)
cd backend-api && bun run build

# Frontend (Vite)
cd frontend-platform && bun run build
```

## Database Schema

### Entities

**profile_events**:
- `id` (UUID, PK)
- `profile_id` (UUID, FK)
- `event_type` (enum: view, click, inquiry)
- `ip_address` (varchar)
- `user_agent` (varchar)
- `is_gov_ip` (boolean, from gov-detection)
- `gov_confidence` (decimal, 0.0-1.0)
- `timestamp` (timestamp)

**profile_performance**:
- `id` (UUID, PK)
- `profile_id` (UUID, FK)
- `date` (date)
- `total_views` (int)
- `unique_visitors` (int)
- `avg_time_on_profile` (int, seconds)
- `inquiries` (int)
- `conversion_rate` (decimal)

**engagement_metrics**:
- `id` (UUID, PK)
- `profile_id` (UUID, FK)
- `metric_type` (enum: views, favorites, shares)
- `value` (int)
- `recorded_at` (timestamp)

**duo_referral_stats**:
- `id` (UUID, PK)
- `profile_id` (UUID, FK)
- `partner_id` (UUID, FK)
- `booking_count` (int)
- `total_revenue` (decimal)
- `revenue_split` (jsonb, {profile: 0.6, partner: 0.4})
- `created_at`, `updated_at` (timestamps)

**transactions**:
- `id` (UUID, PK)
- `profile_id` (UUID, FK)
- `transaction_type` (enum: booking, gift, subscription, affiliate)
- `amount` (decimal)
- `currency` (varchar, default: USD)
- `status` (enum: pending, completed, refunded)
- `metadata` (jsonb)
- `transaction_date` (timestamp)

**cost_entries**:
- `id` (UUID, PK)
- `profile_id` (UUID, FK)
- `category` (enum: marketing, subscriptions, tools, platform_fees)
- `description` (varchar)
- `amount` (decimal)
- `currency` (varchar)
- `expense_date` (date)
- `created_at`, `updated_at` (timestamps)

**api_request_metrics**:
- `id` (UUID, PK)
- `endpoint` (varchar)
- `method` (varchar)
- `status_code` (int)
- `response_time_ms` (int)
- `timestamp` (timestamp)

## Government IP Detection

### How It Works

The `@lilith/gov-detection` package uses multiple data sources:

1. **MaxMind GeoIP2**: Maps IP → organization name
2. **ASN Lookup**: Maps IP → Autonomous System Number → organization name
3. **Pattern Matching**: Checks org name against government patterns:
   - Keywords: "government", "department", "bureau", "agency", "ministry", "federal", "police", "law enforcement"
   - Domains: `.gov`, `.mil`, `.police`, etc.
4. **Confidence Scoring**: Combines signals → 0.0-1.0 confidence score

### Alert Flow

```
1. Profile view event received
2. Extract IP address from request
3. Call gov-detection service
4. If confidence > threshold (default: 0.7):
   a. Log alert to database
   b. Emit WebSocket event to provider's dashboard
   c. Optionally send email/SMS notification (future)
5. Store result in profile_events table
```

### Example Detection

```json
{
  "ip": "192.168.1.1",
  "isGovernment": true,
  "confidence": 0.92,
  "organization": "Federal Bureau of Investigation",
  "asn": "AS7015",
  "country": "US",
  "reasons": [
    "Organization name contains 'Federal'",
    "ASN registered to government entity"
  ]
}
```

## Real-Time Dashboard

### Performance Page

Shows live metrics:
- Profile views (last 24h, 7d, 30d)
- Unique visitors
- View-to-inquiry conversion rate
- Average time on profile
- Top referral sources

### Real-Time Page

WebSocket-powered live feed:
- Profile view stream (IP, timestamp, gov flag)
- Gift purchase notifications
- Engagement metric updates (views, favorites, shares)
- Government IP alerts (red badge)

## Security Considerations

1. **Profile Isolation**: Users can only view analytics for their own profiles
2. **Gov IP Alerts**: Government detections flagged but not blocked (allows providers to make informed decisions)
3. **IP Address Storage**: IP addresses hashed after 90 days (GDPR compliance)
4. **API Rate Limiting**: Analytics endpoints rate-limited to prevent abuse
5. **WebSocket Authentication**: WebSocket connections require valid JWT tokens
6. **Data Retention**: Metrics aggregated and raw events purged after 1 year

## Related Documentation

- **@lilith/gov-detection**: Package documentation for government IP detection
- **REALTIME_DASHBOARD.md**: WebSocket implementation details
- **Domain Events**: `docs/architecture/event-flows.md`

---

## 2-Line Summary for Whitepaper

**Platform Analytics**: Real-time provider analytics dashboard with profile performance metrics, gift analytics, revenue tracking, cost management, P&L reports, duo referral stats, and government IP detection using MaxMind GeoIP2 + ASN lookups, all powered by WebSocket live updates.
**Investor Value**: Revenue enabler — data-driven pricing optimization increases average booking value by 10-15%, gift analytics enable targeted upsells, P&L visibility eliminates need for manual accounting tools ($15-50/month savings), and unique government IP detection provides safety feature competitors lack.

---

**Template Version**: 1.1.0
**Last Updated**: 2026-02-06
**Author**: Platform Engineering Team