lilith/platform-codebase
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1
platform-codebase/features/platform-analytics/docs
History
…
..
README.md

README.md

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

// 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

# 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:

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

Development

Local Setup

# 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

# 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

# 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

{
  "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