469 lines
20 KiB
Markdown
469 lines
20 KiB
Markdown
# 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
|