Nomad Command Center

Operations Intelligence Platform for Nomad Internet - Phase 1

Overview

The Nomad Command Center is a real-time financial and billing automation system designed to:

• Detect free riders - Lines active without payment
• Block unauthorized credits - >$500 requires approval
• Auto-suspend overdue accounts - >3 days overdue
• Provide same-day revenue visibility - No manual KPIs

Architecture

├── backend/           # FastAPI Python backend
│   ├── api/routes/    # REST API endpoints
│   ├── models/        # SQLAlchemy database models
│   ├── services/      # External API clients (Chargebee, Stripe, ThingSpace)
│   └── jobs/          # Background jobs (scanner, watchdog, alerts)
│
├── frontend/          # Next.js React frontend
│   ├── app/           # Pages (dashboard, billing, credits, etc.)
│   ├── components/    # Reusable UI components
│   └── lib/           # API client and utilities
│
└── docker-compose.yml # Local development setup

Quick Start

Prerequisites

• Docker and Docker Compose
• Node.js 20+ (for frontend development)
• Python 3.11+ (for backend development)

Local Development

1. Clone and setup environment:

cp .env.example .env
# Edit .env with your API credentials

2. Start all services:

docker-compose up -d

3. Access the application:

• Frontend: http://localhost:3000
• Backend API: http://localhost:8000
• API Docs: http://localhost:8000/docs

Development Mode

Backend:

cd backend
pip install -r requirements.txt
uvicorn main:app --reload

Frontend:

cd frontend
npm install
npm run dev

API Endpoints

Revenue

• GET /api/revenue/daily - Yesterday's revenue
• GET /api/revenue/monthly - MRR and subscription metrics
• GET /api/revenue/trend?days=7 - Revenue trend
• GET /api/revenue/summary - Dashboard summary

Billing

• GET /api/billing/overdue - Overdue invoices
• GET /api/billing/free-riders - Free rider list
• GET /api/billing/health - Billing health metrics
• POST /api/billing/suspend/{customer_id} - Suspend line

Credits

• POST /api/credits/request - Create credit request
• PUT /api/credits/{id}/approve - Approve credit
• PUT /api/credits/{id}/reject - Reject credit
• GET /api/credits/pending - Pending approvals
• GET /api/credits/analytics/summary - Credit analytics

Alerts

• GET /api/alerts/active - Active alerts
• GET /api/alerts/critical - Critical alerts only
• PUT /api/alerts/{id}/acknowledge - Acknowledge alert
• PUT /api/alerts/{id}/resolve - Resolve alert

Customers

• GET /api/customers - List customers
• GET /api/customers/{id} - Customer detail
• POST /api/customers/sync - Sync from Chargebee

Background Jobs

Job	Frequency	Description
Free Rider Scanner	Hourly	Detects unpaid active lines
Suspension Watchdog	Hourly	Auto-suspends overdue accounts
Alert Engine	15 minutes	Checks alert conditions

Credit Approval Thresholds

Amount	Required Approval
< $50	Agent
$50 - $199	Supervisor
$200 - $499	Manager
>= $500	Director

Deployment (Fly.io)

1. Install Fly CLI:

curl -L https://fly.io/install.sh | sh
fly auth login

2. Create app and database:

fly launch --name nomad-command-center --region den
fly postgres create --name nomad-db --region den
fly postgres attach nomad-db

3. Set secrets:

fly secrets set \
  CHARGEBEE_API_KEY="your_key" \
  STRIPE_SECRET_KEY="your_key" \
  THINGSPACE_USERNAME="your_username" \
  THINGSPACE_PASSWORD="your_password" \
  SLACK_WEBHOOK_URL="your_webhook" \
  SECRET_KEY="your_secret"

4. Deploy:

fly deploy

Environment Variables

Variable	Description	Required
DATABASE_URL	PostgreSQL connection string	Yes
REDIS_URL	Redis connection string	No
CHARGEBEE_API_KEY	Chargebee API key	Yes
CHARGEBEE_SITE	Chargebee site name	Yes
STRIPE_SECRET_KEY	Stripe secret key	Yes
THINGSPACE_USERNAME	Verizon ThingSpace username	Yes
THINGSPACE_PASSWORD	Verizon ThingSpace password	Yes
SLACK_WEBHOOK_URL	Slack webhook for alerts	No
SECRET_KEY	Application secret key	Yes

Phase 1 Deliverables

• Financial Command Center (Revenue Dashboard)
• Free Rider Detection & Reporting
• Auto-Suspension for Overdue Accounts
• Credit Approval Workflow
• Alert System with Slack Integration
• Customer Management Interface

Tech Stack

• Backend: Python, FastAPI, SQLAlchemy, APScheduler
• Frontend: Next.js 14, React, Tailwind CSS, Recharts
• Database: PostgreSQL
• Cache: Redis (optional)
• Deployment: Docker, Fly.io

License

Proprietary - Nomad Internet