Software Architecture
How Lotto Edge is structured — layers, data flow, and technology stack.
Technology Stack
Backend
- FastAPI — async web framework
- Python 3.12+ — runtime
- uv — package manager
- Uvicorn — ASGI server
- SQLAlchemy — ORM / DB layer
- Pydantic — data validation
Frontend
- Jinja2 — server-side templates
- Bootstrap 5 — UI framework
- Chart.js — data visualization
- Bootstrap Icons — icon set
- Google Fonts — DM Sans, IBM Plex, JetBrains Mono
Data & ML
- pandas — data processing
- numpy — numerical computation
- scipy — statistics
- scikit-learn — Random Forest, GBM
- TensorFlow/Keras — LSTM model
- PostgreSQL — persistent storage
System Layers
Layer 1 — Presentation
Jinja2 HTML templates · Bootstrap 5 UI · Chart.js visualizations · Vanilla JS fetch API
Layer 2 — Routing (FastAPI Routers)
dashboard.py · analysis.py · picks.py · jackpot.py · upload.py · about.py · cash5.py · predictions.py
Layer 3 — Services (19 Analysis Modules)
Tier 1 — Statistical
frequency · positional · cluster
balance · sum_range · skip_hit
group_dist · consecutive
frequency · positional · cluster
balance · sum_range · skip_hit
group_dist · consecutive
Tier 2 — Mathematical
probability · coverage
expected_value
probability · coverage
expected_value
Tier 3 — ML/AI
ml_engine (LSTM)
monte_carlo (ensemble)
ml_engine (LSTM)
monte_carlo (ensemble)
Tier 4–5 — Picks
composite_scorer
pick_generator
data_loader
composite_scorer
pick_generator
data_loader
Cash Five Prediction Engine
cash5_predictor — 7 algorithms: frequency/χ², hot/cold, gap analysis, Markov chain, Monte Carlo simulation, pattern recognition, ensemble · split-risk score · EV-after-split
cash5_predictor — 7 algorithms: frequency/χ², hot/cold, gap analysis, Markov chain, Monte Carlo simulation, pattern recognition, ensemble · split-risk score · EV-after-split
Layer 4 — Data
PostgreSQL (DATABASE_URL) · SQLAlchemy ORM · CSV upload parser · ML model storage (ml_models/)
Project Structure
lottoedge/ ├── app/ │ ├── main.py # App entry point │ ├── config.py # Settings │ ├── models/ │ │ ├── database.py # SQLAlchemy models │ │ └── schemas.py # Pydantic schemas │ ├── routers/ │ │ ├── dashboard.py # Main pages │ │ ├── analysis.py # Analysis API │ │ ├── picks.py # Pick generation │ │ ├── upload.py # CSV upload │ │ ├── jackpot.py # Jackpot monitor │ │ ├── cash5.py # Cash Five page │ │ ├── predictions.py # Cash Five API │ │ └── about.py # Docs pages │ ├── core/ │ │ └── rate_limiter.py # slowapi limiter │ ├── services/ # 19 modules + cash5 │ ├── templates/ # Jinja2 HTML │ └── static/ # CSS / JS / img ├── data/ # CSV inputs ├── ml_models/ # Trained models └── tests/ # pytest suite
Data Flow
- CSV Upload — User uploads Texas Lotto, Two Step, or Powerball CSV via /upload
- Parsing — data_loader.py detects game eras, normalizes columns, stores rows in PostgreSQL
- Analysis Request — Browser calls /api/analysis/{game}
- Service Pipeline — Router invokes all 19 modules in sequence against the DB data
- Composite Score — Each number receives a 0–100 score from weighted module outputs
- Pick Generation — Top-scored numbers are assembled into combinations passing all filters
- JSON Response — Results returned to browser; Chart.js renders visualizations
API Endpoints
| Method | Path | Description | Type |
|---|---|---|---|
| Pages | |||
| GET | / | Main analysis dashboard | HTML |
| GET | /history | Historical draw explorer | HTML |
| GET | /picks | Pick generation page | HTML |
| GET | /upload | CSV upload page | HTML |
| GET | /jackpot | Jackpot monitor | HTML |
| GET | /coverage | Wheel / coverage builder | HTML |
| GET | /cash5 | Cash Five prediction page | HTML |
| GET | /architecture | This page | HTML |
| GET | /modules | Module explanations | HTML |
| GET | /faq | Frequently asked questions | HTML |
| Core Analysis API | |||
| POST | /api/upload/{game} | Upload CSV data | JSON |
| GET | /api/analysis/{game} | Full analysis results | JSON |
| GET | /api/frequency/{game} | Frequency data | JSON |
| GET | /api/positional/{game} | Positional matrix | JSON |
| GET | /api/clusters/{game} | Pair / cluster data | JSON |
| GET | /api/skip/{game} | Skip & hit patterns | JSON |
| GET | /api/sum-range/{game} | Sum distribution + 70% band | JSON |
| POST | /api/picks/generate | Generate optimized picks | JSON |
| POST | /api/jackpot/update | Update jackpot amount | JSON |
| GET | /api/jackpot/ev/{game} | Expected value at current jackpot | JSON |
| GET | /api/ml/predict/{game} | ML prediction scores | JSON |
| GET | /api/probability/{game} | Exact probability tables | JSON |
| POST | /api/coverage/build | Build wheeling system | JSON |
| Cash Five Prediction API (rate-limited) | |||
| POST | /api/cash5/history | Insert a Cash Five draw result | JSON |
| GET | /api/cash5/history | List historical Cash Five draws (paginated) | JSON |
| GET | /api/predictions/frequency | Chi-square frequency analysis picks | JSON |
| GET | /api/predictions/hot-cold | Hot / cold rolling-window picks | JSON |
| GET | /api/predictions/gap | Overdue gap analysis picks | JSON |
| GET | /api/predictions/markov | Markov chain transition-matrix picks | JSON |
| GET | /api/predictions/monte-carlo | Monte Carlo simulation picks | JSON |
| GET | /api/predictions/patterns | Pattern recognition picks | JSON |
| POST | /api/predictions/ensemble | Weighted ensemble + split-risk + EV-after-split | JSON |