Merge pull request #22 from ThomasJButler/v1.5

chore: standardise comments to my own style guide

Author: ThomasJButler

README.md

@@ -1,62 +1,162 @@
 # SQL-Ball
 
-SQL-Ball is a football analytics platform that transforms football match data into actionable insights through interactive visualizations and natural language queries. This project was developed as a content project for the **CodeCademy Mastering Generative AI for Developers Bootcamp** held from August to September 2025.
+Football analytics platform that converts natural language questions into SQL queries, processes European league match data, and visualises patterns and statistics.
+
+## What It Does
+
+SQL-Ball lets you:
+- Ask questions about football matches in plain English ("Show me upsets in the Premier League")
+- Get automated SQL query generation and execution
+- View interactive dashboards with historical trends, team performance, and statistical anomalies
+- Explore data across 22 European leagues with 7,600+ matches
+
+The backend uses LangChain RAG (Retrieval-Augmented Generation) to parse queries and retrieve relevant schema context. The frontend provides real-time visualisations via Chart.js.
+
+## Setup
+
+### Prerequisites
+- Node.js 18+
+- Python 3.11+
+- Supabase project (free tier works)
+- OpenAI or Anthropic API key (optional, for AI features)
 
-<img width="1261" height="621" alt="image" src="https://github.com/user-attachments/assets/407966f8-e680-458a-aa7a-a3d66b7d1318" />
+### Installation
 
-## Overview
+**Frontend:**
+```bash
+npm install
+npm run dev
+```
 
-SQL-Ball allows users to:
-- View and analyze historical match data.
-- Filter data by league division (e.g., Premier League, La Liga, Bundesliga).
-- Generate visualizations including trends, distribution charts, and performance radar charts.
-- Execute natural language queries converted to SQL for retrieving football statistics.
+Runs on `http://localhost:5173` by default.
 
-## Architecture & Use Cases
+**Backend:**
+```bash
+cd backend
+python -m venv .venv
+source .venv/bin/activate  # Windows: .venv\Scripts\activate
+pip install -r requirements.txt
+python main.py
+```
 
-For detailed architectural decisions and design patterns used in this project, please refer to [ARCHITECTURE.md](ARCHITECTURE.md).
+Runs on `http://localhost:8000`.
 
-**Key Use Cases:**
-- **Data Filtering:** Filter match data based on league divisions using unique codes such as:
-  - **Premier League (E1)**
-  - **La Liga (SP1)**
-  - **Bundesliga (G1)**
-- **Interactive Visualizations:** Generate charts for goals trends, result distributions, and team performance.
-- **Natural Language Querying:** Allow users to enter plain-English queries that are converted into SQL to retrieve relevant insights.
-- **Backend Integration:** Support backend data processing (Python-based API) and a frontend built with Svelte and Vite.
+**Environment Variables**
 
-## Project Details
-
-- **Frontend:** Built using Svelte and Vite, with visualizations rendered via Chart.js components.
-- **Backend:** Python scripts and APIs serve match data and handle data processing.
-- **Deployment:** Designed to be deployed to Vercel with separate configuration for the backend. Sensitive files like `backend/.env` should be added to `.gitignore` to protect credentials.
-- **Content Project:** This project was created as part of an intensive bootcamp to master generative AI applications in software development.
-
-## Acknowledgements
-
-Thank you for the incredible datasets, this would not be possible without - https://www.football-data.co.uk/data.php
-
-A special thanks to the CodeCademy Mastering Generative AI for Developers Bootcamp for inspiring this project and providing the learning environment that led to its creation. The course and this project in particular were a big learning curve for me and really enjoyed the experience.
-
-## Getting Started
-
-1. **Installation:**
-   - Clone the repository.
-   - Install dependencies using `npm install` for the frontend.
-   - Set up the backend by following the instructions in `backend/setup.sh`.
-   - Ensure you have proper environment variables set up (see `.env.example`).
-
-2. **Development:**
-   - Start the frontend by running `npm run dev`.
-   - For backend development, run the provided scripts in the `backend` directory.
-
-3. **Deployment:**
-   - The project is ready for deployment on Vercel. Make sure to configure environment variables on Vercel and exclude sensitive files (like `backend/.env`) from version control.
+Create `.env` files in both root and `backend/` directories:
+
+```
+# Frontend .env
+VITE_SUPABASE_URL=your_supabase_url
+VITE_SUPABASE_ANON_KEY=your_supabase_key
+VITE_OPENAI_API_KEY=your_openai_key  # Optional
+```
+
+```
+# Backend .env
+VITE_SUPABASE_URL=your_supabase_url
+VITE_SUPABASE_ANON_KEY=your_supabase_key
+VITE_OPENAI_API_KEY=your_openai_key
+```
+
+## Architecture
+
+**Frontend Stack**
+- Svelte + Vite for rapid development
+- Chart.js for visualisations
+- TypeScript for type safety
+- Tailwind CSS for styling
+
+**Backend Stack**
+- FastAPI for HTTP API
+- LangChain for RAG and SQL generation
+- ChromaDB for vector embeddings
+- Supabase PostgreSQL for data
+
+**Data Flow**
+1. User types natural language question
+2. Frontend sends to backend `/query` endpoint
+3. Backend retrieves schema context via embeddings
+4. LLM generates SQL with OpenAI/Anthropic
+5. SQL validation and repair layer handles edge cases
+6. Query executes via Supabase RPC
+7. Results return with explanation
+
+## Common Issues
+
+**"No API key configured"**
+- Add `VITE_OPENAI_API_KEY` to `.env` for AI features
+- Platform still works with template-based query generation
+
+**"Failed to initialise ChromaDB"**
+- Ensure `backend/.venv` is activated
+- Check `chromadb_data/` directory is writable
+- Clear directory and restart if schema changed
+
+**Queries returning empty results**
+- Verify league code is correct (E0 = Premier League, SP1 = La Liga, etc.)
+- Check match_date format in WHERE clause
+- Most data is 2024-2025 season
+
+## Deployment
+
+**Vercel (Frontend)**
+```bash
+npm run build
+# Deploy dist/ folder to Vercel
+```
+
+Set environment variables in Vercel project settings.
+
+**Backend Options**
+- Railway.app (easiest)
+- Heroku (cost-free tier removed)
+- Self-hosted VPS
+
+Backend needs environment variables set on deployment platform.
+
+## Tech Details
+
+**Why This Stack?**
+
+- Svelte: Smaller bundle than React, excellent for data visualisations
+- FastAPI: Modern Python async framework, auto-generates OpenAPI docs
+- LangChain: Handles complex RAG pipelines without reinventing the wheel
+- Supabase: PostgreSQL advantage for complex queries, real-time capabilities
+- ChromaDB: Lightweight embedding store, no external dependency
+
+**Performance Notes**
+
+- Initial schema embedding takes ~2-3 seconds
+- Subsequent queries cache embeddings in memory
+- Vector search dramatically improves context retrieval
+- Falls back to text search if embeddings unavailable
+
+## Data Source
+
+Match data sourced from [football-data.co.uk](https://www.football-data.co.uk/data.php).
+
+Covers:
+- Premier League, Championship, League One, League Two (England)
+- La Liga, Segunda División (Spain)
+- Bundesliga, 2. Bundesliga (Germany)
+- Serie A, Serie B (Italy)
+- Ligue 1, Ligue 2 (France)
+- Eredivisie (Netherlands)
+- Pro League (Belgium)
+- Primeira Liga (Portugal)
+- Süper Lig (Turkey)
+- Super League (Greece)
+- Premiership, Championship, League One, League Two (Scotland)
 
 ## Contributing
 
-Contributions are welcome! Please check the issues and submit pull requests for enhancements or bug fixes. For major changes, please open an issue first to discuss the proposed changes.
+Issues and pull requests welcome. For major changes, open an issue first to discuss.
 
 ## License
 
-This project is licensed under the terms described in the [LICENSE](LICENSE) file.
+See [LICENSE](LICENSE) file for details.
+
+---
+
+Built as a CodeCademy Mastering Generative AI for Developers bootcamp project (August-September 2025).

backend/api/execute.py

@@ -1,5 +1,8 @@
 """
-SQL Execution API endpoints for SQL-Ball
+@author Tom Butler
+@date 2025-10-21
+@description SQL execution endpoint. Receives SQL queries, applies PostgreSQL compatibility fixes,
+             validates them, and executes via Supabase RPC. Handles error cases and season validation.
 """
 
 from fastapi import APIRouter, HTTPException
@@ -38,7 +41,7 @@ async def execute_sql_query(request: ExecuteRequest):
     """
     try:
         # Debug logging
-        print(f"🔍 DEBUG: Received SQL query: {request.sql}")
+        print(f"DEBUG: Received SQL query: {request.sql}")
 
         # Clean the SQL - remove trailing semicolon for Supabase RPC
         clean_sql = request.sql.strip().rstrip(';')
@@ -56,14 +59,14 @@ async def execute_sql_query(request: ExecuteRequest):
         # AGGRESSIVE FIX: Detect and fix conflicting season conditions
         season_matches = re.findall(r"season\s*=\s*['\"]([^'\"]+)['\"]", clean_sql, re.IGNORECASE)
         if len(season_matches) > 1 and len(set(season_matches)) > 1:
-            print(f"🚨 EXECUTE: Found conflicting seasons: {season_matches}")
+            print(f"EXECUTE: Found conflicting seasons: {season_matches}")
             # Keep only the first season condition
             first_season = season_matches[0]
             clean_sql = re.sub(r"season\s*=\s*['\"][^'\"]+['\"]", f"season = '{first_season}'", clean_sql, flags=re.IGNORECASE)
             # Clean up multiple ANDs
             clean_sql = re.sub(r"\bAND\s+season\s*=\s*['\"][^'\"]+['\"]", "", clean_sql, flags=re.IGNORECASE)
             clean_sql = re.sub(r"\bAND\s+AND\b", "AND", clean_sql, flags=re.IGNORECASE)
-            print(f"🔧 EXECUTE: Fixed to use only '{first_season}': {clean_sql}")
+            print(f"EXECUTE: Fixed to use only '{first_season}': {clean_sql}")
 
         # CRITICAL POSTGRESQL FIXES:
         # Fix boolean comparisons: finished = 1 -> finished = true
@@ -73,9 +76,9 @@ async def execute_sql_query(request: ExecuteRequest):
         # Fix column names that don't exist
         clean_sql = re.sub(r'\bdate\b', 'kickoff_time', clean_sql, flags=re.IGNORECASE)
 
-        print(f"🔧 EXECUTE: Applied PostgreSQL fixes: {clean_sql}")
-        
-        print(f"🔍 DEBUG: Fixed SQL query: {clean_sql}")
+        print(f"EXECUTE: Applied PostgreSQL fixes: {clean_sql}")
+
+        print(f"DEBUG: Fixed SQL query: {clean_sql}")
 
         # Validate it's a SELECT query for security
         if not clean_sql.upper().strip().startswith('SELECT'):
@@ -111,8 +114,8 @@ async def execute_sql_query(request: ExecuteRequest):
         raise
     except Exception as e:
         # Log the full error for debugging
-        print(f"🚨 ERROR: SQL execution failed: {str(e)}")
-        print(f"🚨 SQL that failed: {clean_sql}")
+        print(f"ERROR: SQL execution failed: {str(e)}")
+        print(f"SQL that failed: {clean_sql}")
 
         # Return more specific error messages
         if "does not exist" in str(e).lower():

backend/api/optimize.py

@@ -1,5 +1,8 @@
 """
-Query Optimization API endpoints
+@author Tom Butler
+@date 2025-10-21
+@description Query optimisation API endpoints. Analyses SQL for performance improvements,
+             discovers patterns in queries, generates suggestions, and explains query execution plans.
 """
 
 from fastapi import APIRouter, HTTPException
@@ -194,25 +197,25 @@ async def explain_query_plan(sql: str):
     # Analyze query components
     if "SELECT" in sql_upper:
         if "*" in sql:
-            explanation_parts.append("📊 Selecting all columns (consider specifying only needed columns)")
+            explanation_parts.append("Selecting all columns (consider specifying only needed columns)")
         else:
-            explanation_parts.append("✅ Selecting specific columns (good practice)")
+            explanation_parts.append("Selecting specific columns (good practice)")
 
     if "JOIN" in sql_upper:
         join_count = sql_upper.count("JOIN")
-        explanation_parts.append(f"🔗 Joining {join_count} table(s)")
+        explanation_parts.append(f"Joining {join_count} table(s)")
 
     if "WHERE" in sql_upper:
-        explanation_parts.append("🔍 Filtering results with WHERE clause")
+        explanation_parts.append("Filtering results with WHERE clause")
 
     if "GROUP BY" in sql_upper:
-        explanation_parts.append("📈 Grouping results for aggregation")
+        explanation_parts.append("Grouping results for aggregation")
 
     if "ORDER BY" in sql_upper:
-        explanation_parts.append("🔤 Sorting results")
+        explanation_parts.append("Sorting results")
 
     if "LIMIT" in sql_upper:
-        explanation_parts.append("✂️ Limiting result set size")
+        explanation_parts.append("Limiting result set size")
 
     # Performance estimate
     estimated_speed = "Fast"

backend/api/query.py

@@ -1,5 +1,8 @@
 """
-Query API endpoints for SQL-Ball
+@author Tom Butler
+@date 2025-10-21
+@description Natural language query API endpoint. Converts plain English questions into SQL queries,
+             retrieves schema context, validates input, and returns results with explanations.
 """
 
 from fastapi import APIRouter, HTTPException, Depends
@@ -75,8 +78,8 @@ async def process_natural_language_query(request: QueryRequest):
 
     except Exception as e:
         # Log the full error for debugging
-        print(f"🚨 ERROR: Query processing failed: {str(e)}")
-        print(f"🚨 Question: {request.question}")
+        print(f"ERROR: Query processing failed: {str(e)}")
+        print(f"Question: {request.question}")
 
         # Return more specific error messages
         error_msg = str(e).lower()

backend/main.py

@@ -1,6 +1,9 @@
 """
-SQL-Ball FastAPI Backend
-RAG-powered football analytics with natural language to SQL conversion
+@author Tom Butler
+@date 2025-10-21
+@description FastAPI backend server for SQL-Ball. Initialises RAG components (schema embeddings,
+             SQL chain, football terminology mapper) on startup. Configures CORS and exposes
+             API routers for query processing, optimisation, and execution.
 """
 
 from fastapi import FastAPI, HTTPException
@@ -53,7 +56,7 @@ async def startup_event():
     """Initialize RAG components on startup"""
     global schema_embedder, sql_chain, football_mapper
 
-    print("🚀 Initializing SQL-Ball RAG system...")
+    print("Initialising SQL-Ball RAG system...")
 
     # Initialize schema embedder
     schema_embedder = SchemaEmbedder()
@@ -69,7 +72,7 @@ async def startup_event():
     set_query_deps(sql_chain, schema_embedder)
     set_sql_chain(sql_chain)
 
-    print("✅ RAG system initialized successfully!")
+    print("RAG system initialised successfully!")
 
 # Include routers
 app.include_router(query_router, prefix="/api")