SuperSkin Architecture

Version: 3.0 Last Updated: January 2026 Status: Production Implementation

What This Document Covers

This is the authoritative architecture guide for SuperSkin, a suite of microservices that provide AI-powered trading tools for sports betting. It describes:

What we are building (the 5 core services)
How data flows through the system
How SuperSkin connects to the Oracle Platform and Forsyt Data Machine
Deployment and infrastructure details

The Three Pillars

SuperSkin sits at the intersection of three major systems:

System	Repository	What It Does
Oracle Platform	`smartbets-protocol/oracle-platform`	Aggregates real-time sports data from vendors (Oddspapi, Sportmonks, Roanuz, API-Tennis, Betfair)
Forsyt Data Machine	`forsyt-data-machine/`	Historical data warehouse with ML training infrastructure
SuperSkin	This monorepo	6 microservices that consume data and provide trading intelligence

The 6 Core Services

These are the production services we are building and deploying:

#	Service	Port	Stack	Purpose
1	Price Feed Aggregator	3100	TypeScript/Express	Aggregates odds from Oracle Platform and external APIs
2	Cash Out Calculator	3101	TypeScript/Express	Calculates fair cash-out values for open positions
3	AI Value Detection	3102	Python/FastAPI	Detects mispriced odds using Shin, Poisson, and ELO models
4	AI Chat Assistant	3103	Python/FastAPI	Conversational assistant with RAG and function calling
5	Trading Charts	3104	TypeScript/Express	OHLC data aggregation for candlestick charts
6	SuperSkin Platform	3106	TypeScript/Express	User context, watchlists, alerts, preferences

Supporting Services

Service	Port	Stack	Purpose
ML Prediction Service	3105	Python/FastAPI	Serves ONNX models for match outcome prediction
ML Training Pipeline	N/A	Python/scikit-learn	Offline training on Forsyt Data Machine

Infrastructure

Component	Port	Purpose
Redis	6380	Pub/Sub messaging, caching, price history
TimescaleDB	5433	Time-series storage for OHLC data
PostgreSQL (Main)	5432	Main database (via Forsyt Data Machine)
PostgreSQL (Platform)	5434	SuperSkin Platform database (watchlists, alerts, chat)

How Data Flows

The system has three distinct data flows:

1. Real-Time Match Data (Oracle → SuperSkin)

The Oracle Platform aggregates data from 5 vendor APIs and publishes updates every 60 seconds.

2. AI Analysis Pipeline (SuperSkin Internal)

When a user requests value bets, multiple services collaborate:

3. Historical Data Flow (Data Machine → ML)

Training happens offline using data from Forsyt Data Machine:

Service Architecture Details

1. Price Feed Aggregator (Port 3100)

Purpose: Aggregate real-time odds from Oracle Platform and external APIs into a unified price feed.

Technology Stack:

TypeScript / Express.js
Redis for caching and pub/sub
TimescaleDB for historical storage

Key Responsibilities:

Subscribe to Oracle Platform price updates via Redis
Normalize prices across bookmakers
Calculate fair value using Shin method
Publish unified prices to Redis channels

API Endpoints:

Endpoint	Method	Description
`/api/prices/:marketId`	GET	Current prices for a market
`/api/prices/fair/:marketId`	GET	Fair value calculation
`/api/prices/history/:marketId`	GET	Historical price data
`/health`	GET	Service health check

2. Cash Out Calculator (Port 3101)

Purpose: Calculate real-time cash-out values for open positions.

Technology Stack:

TypeScript / Express.js
Redis for price caching

Key Responsibilities:

Calculate cash-out value for any position
Support full, partial, and auto cash-out
Real-time quote generation with expiry
Integration with order execution

API Endpoints:

Endpoint	Method	Description
`/api/quote/:positionId`	GET	Get cash-out quote
`/api/execute/:positionId`	POST	Execute cash-out
`/api/auto-cashout`	POST	Set auto cash-out trigger
`/health`	GET	Service health check

Cash Out Formula:

For a BACK bet:

Cash Out Value = (Original Odds / Current Lay Price) × Stake
Profit Locked = Cash Out Value - Original Stake

For a LAY bet:

Cash Out Value = (Current Back Price / Original Odds) × Liability
Profit Locked = Original Liability - Cash Out Value

3. AI Value Detection (Port 3102)

Purpose: Identify betting opportunities where odds offer positive expected value using Shin, Poisson, and ELO models from Forsyt Data Machine.

Technology Stack:

Python / FastAPI
Algorithms from Forsyt Data Machine (Shin, Poisson, ELO)
Redis for caching
PostgreSQL for historical data

Key Responsibilities:

Calculate fair odds using Shin method (removes bookmaker margin)
Generate predictions using Poisson model (goal-based)
Maintain ELO ratings for teams
Compare market prices to fair odds
Calculate edge for each outcome

API Endpoints:

Endpoint	Method	Description
`/api/value/signals`	GET	Current value signals
`/api/value/detect`	POST	Detect value for specific match
`/api/value/history`	GET	Historical signal performance
`/health`	GET	Service health check

Value Detection Algorithm:

4. AI Chat Assistant (Port 3103)

Purpose: Natural language interface for betting assistance with native search, RAG, and function calling.

Technology Stack:

Python / FastAPI
Primary LLM: Grok/xAI (grok-4) with native X Search and Web Search
Fallback Providers: Groq (llama-3.3-70b), Ollama (local)
pgvector for embeddings (RAG)
Redis for conversation cache

Key Responsibilities:

Natural language query understanding
Native X Search for real-time sports news and sentiment
Native Web Search for live match information
Tool-based function calling for data retrieval
RAG over historical betting data
Integration with other SuperSkin services

API Endpoints:

Endpoint	Method	Description
`/api/chat`	POST	Send chat message
`/api/chat/stream`	POST	Streaming chat response
`/api/history/:sessionId`	GET	Get chat history
`/health`	GET	Service health check

LLM Provider Architecture:

Grok Native Search Capabilities:

Tool	Purpose	Use Case
X Search	Search X (Twitter) in real-time	Team news, injury updates, betting sentiment
Web Search	Search the web	Live scores, match previews, team news

Available Tools (Function Calling):

Tool	Description
`get_market_prices`	Current prices from Price Feed
`get_value_signals`	Value signals from AI Value Detection
`get_team_history`	Historical team performance
`get_head_to_head`	H2H stats between teams
`calculate_cash_out`	Cash out value from Cash Out Calculator

5. Trading Charts (Port 3104)

Purpose: OHLC data aggregation and real-time charting backend.

Technology Stack:

TypeScript / Express.js
Redis for real-time tick data
TimescaleDB for historical OHLC storage

Key Responsibilities:

Aggregate price ticks into OHLC candles
Store historical data in TimescaleDB
Serve OHLC data via REST API
Stream real-time updates via WebSocket

API Endpoints:

Endpoint	Method	Description
`/api/ohlc/:marketId`	GET	Historical OHLC data
`/api/ohlc/:marketId/latest`	GET	Latest candle
`/ws`	WebSocket	Real-time tick stream
`/health`	GET	Service health check

ML Infrastructure

ML Prediction Service (Port 3105)

Purpose: Serve trained ML models for real-time match predictions.

Technology Stack:

Python / FastAPI
ONNX Runtime for inference
Redis for prediction caching

Model Ensemble:

ML Training Pipeline (Offline)

Purpose: Train models on historical data from Forsyt Data Machine.

Training Flow:

Integration with External Systems

Forsyt Data Machine

The Forsyt Data Machine is the data backbone providing:

Component	Purpose
Data Harness	Downloads data from 10+ free sources
Algorithms	Shin, Poisson, ELO calculations
ML Pipeline	Feature engineering and model training

Oracle Platform (smartbets-protocol)

The Oracle Platform provides real-time sports data:

Capability	Description
Match Scheduling	Live match data from Oddspapi
Price Streaming	Real-time odds via WebSocket
Result Settlement	Match outcomes for settlement

Deployment Architecture

Docker Compose Stack

# docker-compose.yml overview
services:
  # Infrastructure
  redis:                    # Port 6380 - Cache & Pub/Sub
  timescaledb:              # Port 5433 - Time-series data

  # Core Services (3100 range)
  price-feed-aggregator:    # Port 3100
  cash-out-calculator:      # Port 3101
  ai-value-detection:       # Port 3102
  ai-chat-assistant:        # Port 3103
  trading-charts:           # Port 3104

  # ML Services
  ml-prediction-service:    # Port 3105

Environment Configuration

Variable	Service	Description
`REDIS_URL`	All	Redis connection string
`TIMESCALE_URL`	Price Feed, Charts	TimescaleDB connection
`DATABASE_URL`	AI Services	PostgreSQL (Data Machine)
`GROK_API_KEY`	AI Chat	Grok/xAI primary LLM API key
`GROQ_API_KEY`	AI Chat	Groq fallback LLM API key

API Reference

Service Endpoints Summary

Service	Port	Endpoint	Method	Description
Price Feed	3100	`/api/prices/:marketId`	GET	Current prices
Price Feed	3100	`/api/prices/fair/:marketId`	GET	Fair value calculation
Cash Out	3101	`/api/quote/:positionId`	GET	Cash out quote
Cash Out	3101	`/api/execute/:positionId`	POST	Execute cash out
AI Value	3102	`/api/value/signals`	GET	Current value signals
AI Value	3102	`/api/value/detect`	POST	Detect value for match
AI Chat	3103	`/api/chat`	POST	Send chat message
AI Chat	3103	`/api/history/:sessionId`	GET	Get chat history
Trading Charts	3104	`/api/charts/ohlc/:marketId`	GET	Historical OHLC data
Trading Charts	3104	`/api/watchlist/charts`	GET	OHLC data for watchlist items (auth required)
Trading Charts	3104	`/api/watchlist/overlay/:selectionId`	GET	Check if selection is in watchlist
Trading Charts	3104	`/api/watchlist/selections`	GET	Get all watchlist selection IDs (auth required)
Trading Charts	3104	`/ws/charts`	WebSocket	Real-time tick stream
Trading Charts	3104	`/ws/watchlist`	WebSocket	Watchlist notifications (auth required)
ML Predict	3105	`/predict`	POST	Get match prediction

Security Considerations

API Security

Layer	Mechanism
Authentication	JWT tokens from Backend API
Rate Limiting	Per-IP and per-user limits
Input Validation	Pydantic/Zod schemas
CORS	Whitelist allowed origins

Data Security

Concern	Mitigation
Chat Privacy	Conversations deleted after 30 days
API Keys	Environment variables, never in code
User Data	Minimal collection, no training

Performance Targets

Metric	Target	Measurement
Price Update Latency	<100ms	Time from source to frontend
Prediction Latency	<200ms	Time for ML inference
Cash Out Quote	<500ms	Full quote generation
Chat Response	<3s	First token streaming
Uptime	99.9%	Service availability

Current Status

Service	Status	Notes
Price Feed Aggregator	✅ Implemented	Port 3100
Cash Out Calculator	✅ Implemented	Port 3101
AI Value Detection	✅ Implemented	Port 3102
AI Chat Assistant	✅ Implemented	Port 3103
Trading Charts	✅ Implemented	Port 3104
ML Prediction Service	✅ Implemented	Port 3105
ML Training Pipeline	🔄 In Progress	Training on Data Machine

Repository	Purpose
`smartbets-protocol/oracle-platform`	Real-time sports data aggregation
`forsyt-data-machine`	Historical data warehouse and ML training
`gta-frontend`	React frontend application

What This Document Covers​

The Three Pillars​

The 6 Core Services​

Supporting Services​

Infrastructure​

How Data Flows​

1. Real-Time Match Data (Oracle → SuperSkin)​

2. AI Analysis Pipeline (SuperSkin Internal)​

3. Historical Data Flow (Data Machine → ML)​

Service Architecture Details​

1. Price Feed Aggregator (Port 3100)​

2. Cash Out Calculator (Port 3101)​

3. AI Value Detection (Port 3102)​

4. AI Chat Assistant (Port 3103)​

5. Trading Charts (Port 3104)​

ML Infrastructure​

ML Prediction Service (Port 3105)​

ML Training Pipeline (Offline)​

Integration with External Systems​

Forsyt Data Machine​

Oracle Platform (smartbets-protocol)​

Deployment Architecture​

Docker Compose Stack​

Environment Configuration​

API Reference​

Service Endpoints Summary​

Security Considerations​

API Security​

Data Security​

Performance Targets​

Current Status​

Related Repositories​

What This Document Covers

The Three Pillars

The 6 Core Services

Supporting Services

Infrastructure

How Data Flows

1. Real-Time Match Data (Oracle → SuperSkin)

2. AI Analysis Pipeline (SuperSkin Internal)

3. Historical Data Flow (Data Machine → ML)

Service Architecture Details

1. Price Feed Aggregator (Port 3100)

2. Cash Out Calculator (Port 3101)

3. AI Value Detection (Port 3102)

4. AI Chat Assistant (Port 3103)

5. Trading Charts (Port 3104)

ML Infrastructure

ML Prediction Service (Port 3105)

ML Training Pipeline (Offline)

Integration with External Systems

Forsyt Data Machine

Oracle Platform (smartbets-protocol)

Deployment Architecture

Docker Compose Stack

Environment Configuration

API Reference

Service Endpoints Summary

Security Considerations

API Security

Data Security

Performance Targets

Current Status

Related Repositories