Cartrack LTV & Pricing Engine

Platform documentation v1.0 · Last updated March 2026

1. Overview

The Cartrack Contract Intelligence Platform is a full-stack analytics application that provides four stakeholder dashboards covering Life Time Value determination, churn analytics, pricing optimisation, and model governance.

Tech Stack

2. Architecture

System Architecture

FIG 1 — Layered architecture: Client → API → Analytics → Database

Module Structure

Life Expectancy/
├── backend/
│   ├── main.py              FastAPI app entry point, lifespan, routers, static files
│   ├── config.py            Pydantic settings (discount rate, DB URL, etc.)
│   ├── database.py          SQLAlchemy engine, SessionLocal, Base, get_db()
│   ├── models/              SQLAlchemy ORM models (10 tables)
│   │   ├── contract.py      Core entity — full subscription lifecycle
│   │   ├── customer.py      Subscriber profile + credit band
│   │   ├── payment.py       Monthly billing records
│   │   ├── product.py       Subscription package catalogue
│   │   ├── cost.py          CostUpfront + CostMonthly line items
│   │   ├── hardware.py      Hardware unit + FitmentRecord
│   │   ├── support.py       Support tickets (incl. cancellation requests)
│   │   └── recovery.py      Vehicle theft + recovery events
│   ├── analytics/           Pure Python analytics modules
│   │   ├── ltv.py           LTV formula, Monte Carlo CI, portfolio aggregation
│   │   ├── churn.py         XGBoost churn scorer, preservation queue
│   │   ├── collections.py   Bad billing EV decision model
│   │   └── pricing.py       Constrained price optimisation
│   ├── api/                 FastAPI route handlers
│   │   ├── management.py    C-Suite endpoints (portfolio, waterfall, cohort, etc.)
│   │   ├── sales.py         Sales endpoints (pricing, LTV by segment, funnel)
│   │   ├── retentions.py    Retentions endpoints (queue, collections, notices)
│   │   └── governance.py    Governance endpoints (registry, drift, audit log)
│   └── data/
│       └── seed.py          Synthetic data generator (5,000 contracts)
├── frontend/
│   ├── assets/
│   │   ├── design-system.css  Goldman Sachs terminal CSS variables + components
│   │   └── api-client.js      API helpers, fmt utilities, Plotly dark theme
│   ├── index.html           Landing page + live KPI strip
│   ├── sales.html           Sales & Marketing dashboard
│   ├── management.html      C-Suite Management dashboard
│   ├── retentions.html      Retentions & Collections dashboard
│   ├── governance.html      Model Governance dashboard
│   └── wiki.html            This documentation page
├── tests/                   pytest test suite (233 tests)
├── pytest.ini
├── start.bat / start.sh     Quick-start scripts
└── CLAUDE.md                Project rules and context

Data Flow Pipeline

FIG 2 — End-to-end data flow: Sources → Ingest → Store → Compute → Serve → Render

3. Business Model

Subscription Mechanics

Cartrack sells vehicle tracking subscriptions on a recurring monthly fee basis. Each contract has a cancellation clause (minimum term, typically 36 months) that penalises early termination.

Contract Lifecycle

FIG 3 — Contract state machine: subscription lifecycle from sale to cancellation

Cost Structure

Bad Billing Decision Framework

When a subscriber stops paying, three actions are evaluated each month using Expected Value maximisation:

P(resume payment) decays exponentially with time in bad billing:

FIG 4 — Bad billing EV decision flow: monthly evaluation of three action paths

4. Data Schema

contracts

Core entity. One row per subscription contract.

customers

payments

products

costs_upfront & costs_monthly

hardware & fitment_records

support_tickets

recovery_events

5. Analytical Models

5.1 LTV Engine — backend/analytics/ltv.py

Algorithm: Parametric Survival + DCF Horizon: 60 months Discount rate: 12% annual WACC → 0.949% monthly

Full forward-looking LTV formula:

WHERE

FIG 5 — LTV decomposition: revenue streams vs cost components with key drivers

Confidence interval: Monte Carlo (200 simulations). Samples monthly_churn_prob ~ N(μ, 0.25μ) and net_cashflow ~ N(μ, 0.15μ). Returns P10/P90 as the 80% CI.

Payback month: First month where cumulative discounted cashflow turns non-negative (upfront cost recovered).

6. API Reference

Base URL: http://localhost:8000/api/v1/ · Interactive docs: /docs

Management

Sales

Retentions

Governance & System

7. Dashboard Guide

8. Deployment

Prerequisites

Python 3.11+
pip install -r backend/requirements.txt

Start Server

# Option 1: direct
python -m uvicorn backend.main:app --host 0.0.0.0 --port 8000 --reload

# Option 2: Windows double-click
start.bat

# Option 3: Linux / Mac
bash start.sh

Access

Dashboards:   http://localhost:8000/
API docs:     http://localhost:8000/docs
Health:       http://localhost:8000/health

Fresh Seed

# Delete the database to force a fresh 5,000-contract seed on next startup
del cartrack_ltv.db        # Windows
rm cartrack_ltv.db         # Linux / Mac

# Quick test seed (200 contracts)
python -c "from backend.database import SessionLocal; from backend.data.seed import run_seed; db=SessionLocal(); run_seed(db, n_contracts=200)"

Environment Variables (.env)

Run Tests

# All tests (excludes slow XGBoost training by default)
python -m pytest tests/ -v

# Analytics only
python -m pytest tests/test_analytics_*.py -v

# API integration tests
python -m pytest tests/test_api_*.py -v

# With coverage
python -m pytest tests/ --cov=backend --cov-report=term-missing

High Availability (Production)

The platform is designed for single-node development but supports multi-node production deployment with the following HA configuration:

9. Model Governance

Model Registry

PSI Thresholds (Population Stability Index)

Audit Log Event Types

10. Glossary