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
- SQLite — 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
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
Layer 4 — Data
SQLite (data/lottoedge.db) · 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 │ │ └── about.py # Docs pages │ ├── services/ # 19 modules │ ├── templates/ # Jinja2 HTML │ └── static/ # CSS / JS / img ├── data/ # SQLite + CSVs ├── 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 SQLite
- 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 |
|---|---|---|---|
| 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 | /architecture | This page | HTML |
| GET | /modules | Module explanations | HTML |
| GET | /faq | Frequently asked questions | HTML |
| 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 |