Cass library test

.vercel/README.txt

@@ -0,0 +1,11 @@
+> Why do I have a folder named ".vercel" in my project?
+The ".vercel" folder is created when you link a directory to a Vercel project.
+
+> What does the "project.json" file contain?
+The "project.json" file contains:
+- The ID of the Vercel project that you linked ("projectId")
+- The ID of the user or team your Vercel project is owned by ("orgId")
+
+> Should I commit the ".vercel" folder?
+No, you should not share the ".vercel" folder with anyone.
+Upon creation, it will be automatically added to your ".gitignore" file.

.vercel/project.json

@@ -0,0 +1 @@
+{"projectId":"prj_tWe6TAwUw5OOW79yZbgMfD3sAIgE","orgId":"team_EfHbtzBZ3bpR1FqmNcpTio2k"}

.vscode/launch.json

@@ -0,0 +1,19 @@
+{
+	"configurations": [
+		{
+			"name": "Docker: Python - Flask",
+			"type": "docker",
+			"request": "launch",
+			"preLaunchTask": "docker-run: debug",
+			"python": {
+				"pathMappings": [
+					{
+						"localRoot": "${workspaceFolder}",
+						"remoteRoot": "/app"
+					}
+				],
+				"projectType": "flask"
+			}
+		}
+	]
+}

.vscode/settings.json

@@ -0,0 +1,19 @@
+{
+    "workbench.colorCustomizations": {
+        "activityBar.activeBackground": "#82e4ff",
+        "activityBar.activeBorder": "#ff40d6",
+        "activityBar.background": "#82e4ff",
+        "activityBar.foreground": "#15202b",
+        "activityBar.inactiveForeground": "#15202b99",
+        "activityBarBadge.background": "#ff40d6",
+        "activityBarBadge.foreground": "#15202b",
+        "statusBar.background": "#4fd9ff",
+        "statusBar.foreground": "#15202b",
+        "statusBarItem.hoverBackground": "#1cceff",
+        "titleBar.activeBackground": "#4fd9ff",
+        "titleBar.activeForeground": "#15202b",
+        "titleBar.inactiveBackground": "#4fd9ff99",
+        "titleBar.inactiveForeground": "#15202b99"
+    },
+    "peacock.color": "#4fd9ff"
+}

.vscode/tasks.json

@@ -0,0 +1,38 @@
+{
+	"version": "2.0.0",
+	"tasks": [
+		{
+			"type": "docker-build",
+			"label": "docker-build",
+			"platform": "python",
+			"dockerBuild": {
+				"tag": "lcc:latest",
+				"dockerfile": "${workspaceFolder}/Dockerfile",
+				"context": "${workspaceFolder}",
+				"pull": true
+			}
+		},
+		{
+			"type": "docker-run",
+			"label": "docker-run: debug",
+			"dependsOn": ["docker-build"],
+			"dockerRun": {
+				"env": {
+					"FLASK_APP": "api\\main.py"
+				}
+			},
+			"python": {
+				"args": [
+					"run",
+					"--no-debugger",
+					"--no-reload",
+					"--host",
+					"0.0.0.0",
+					"--port",
+					"5000"
+				],
+				"module": "flask"
+			}
+		}
+	]
+}

README.md

@@ -1,30 +1,133 @@
-# LCC
-Repository for the LCC, League Community Cup, data processing scripts. 
+# LCC API
+
+REST API for the League Community Cup (LCC) — handles match ingestion, player profiles, team management, tournament entries, and league-wide stat aggregations.
+
+Built with **Flask**, **MongoDB Atlas (PyMongo)**, and the **Riot Games API**.
+
+---
+
+## Data Model
+
+Matches are stored in two MongoDB collections:
+
+| Collection | Purpose |
+|---|---|
+| `matches` | Full match archive (team rosters, bans, objectives, scoreboard) |
+| `match_performances` | Fact table — one document per player per match. Used for all stat aggregations. |
+| `players` | Player profiles (no embedded match history) |
+| `teams` | Team metadata and season rosters |
+| `practice` | Practice session records |
+| `tournaments` / `tournament_codes` | Tournament bracket data |
+
+`match_performances` is the single source of truth for stats. It is populated automatically when matches are added or refreshed, and can be rebuilt from `matches` using the migration script.
+
+---
 
 ## Prerequisites
-### Riot API
-To use the fetch, you will need to create a Riot account and generate a riot API key.  Learn more by visiting https://developer.riotgames.com/docs/portal.  
 
-Create a ```.env``` file and add
+### Environment Variables
+
+Create a `.env` file in the project root:
+
 ```
-RIOT_API_KEY='your-key-here'
+RIOT_API_KEY=your-riot-api-key
+MONGO_URI=your-mongodb-atlas-connection-string
+MONGO_COLLECTION=your-database-name
+ADMIN_PW=your-admin-password
+DISCORD_CLIENT_ID=your-discord-client-id
+DISCORD_CLIENT_SECRET=your-discord-client-secret
+DISCORD_REDIRECT_URI=your-discord-redirect-uri
+SECRET_KEY=your-flask-secret-key
 ```
 
+A Riot API key can be obtained at https://developer.riotgames.com/docs/portal.
+
 ### Dependency Installation
 
-1. Activate your virtual environment
-2. Run ```pip install -r requirements.txt```
+```bash
+python -m venv .venv
+source .venv/Scripts/activate   # Windows: .venv\Scripts\activate
+pip install -r requirements.txt
+```
 
-## Adding Match Data
+---
 
-The script will pull match IDs from the ```tournaments``` directory.  To create a new tournament, simply add a ```.txt``` file to that directory and list the match IDs (one per line).  Example match IDs can be found below
+## Running the API
 
+```bash
+flask --app lcc.main run
 ```
-4945781121
-4941568096
+
+Or via the Docker tasks defined in `.vscode/tasks.json`.
+
+---
+
+## API Routes
+
+### Matches — `/matches`
+
+| Method | Route | Description |
+|---|---|---|
+| `GET` | `/matches` | All matches, sorted by date descending |
+| `POST` | `/matches/add` | Add or update a match from a Riot match ID (admin) |
+| `POST` | `/matches/manual` | Add or update a manually entered match (admin) |
+| `POST` | `/matches/refresh` | Re-fetch all matches from Riot API via matches_index (admin) |
+| `GET` | `/matches/<match_id>` | Single match by Riot ID |
+| `GET` | `/matches/lcc/<lcc_id>` | Single match by LCC ID |
+| `PATCH` | `/matches/lcc/<lcc_id>/mvp` | Assign MVP for a match (admin) |
+| `PATCH` | `/matches/<match_id>/vod` | Set VOD URL for a match (admin) |
+| `GET` | `/matches/seasons` | List of all distinct season identifiers |
+| `GET` | `/matches/stats/season/<season_id>` | Aggregated player stats for a season |
+| `GET` | `/matches/stats/alltime` | Aggregated player stats all-time |
+| `GET` | `/matches/champion-stats/season/<season_id>` | Champion stats for a season |
+| `GET` | `/matches/champion-stats/alltime` | Champion stats all-time |
+| `GET` | `/matches/champion/<champion_name>/matches` | All appearances for a champion |
+
+### Players — `/players`
+
+| Method | Route | Description |
+|---|---|---|
+| `GET` | `/players` | All player profiles |
+| `POST` | `/players/add` | Add or update a player (admin) |
+| `GET` | `/players/<puuid>` | Single player profile |
+| `POST` | `/players/<puuid>/refresh` | Refresh Riot data for a player |
+| `GET` | `/players/<puuid>/matches` | Paginated match history (`page`, `per_page`, `champion`) |
+| `GET` | `/players/<puuid>/champion-stats` | Per-champion stats for a player |
+| `GET` | `/players/unclaimed` | Players without a linked Discord account |
+| `POST` | `/players/<puuid>/link-discord` | Link a Discord account to a player (admin) |
+| `DELETE` | `/players/<puuid>/delete` | Remove a match history entry by index (admin) |
+
+### Teams — `/teams`
+
+| Method | Route | Description |
+|---|---|---|
+| `GET` | `/teams` | All teams |
+| `GET` | `/teams/<team_name>` | Single team with roster |
+| `GET` | `/teams/<team_name>/records` | Win/loss records and stats for a team |
+
+### Auth — `/`
+
+| Method | Route | Description |
+|---|---|---|
+| `GET` | `/login` | Discord OAuth2 redirect |
+| `GET` | `/callback` | Discord OAuth2 callback |
+| `GET` | `/me` | Current logged-in player profile |
+| `POST` | `/logout` | Clear session cookie |
+
+---
+
+## Tools
+
+### `tools/migrate_to_match_performances.py`
+
+One-time migration script that reads all documents from `matches` and populates the `match_performances` collection. Also creates the required compound indexes.
+
+Safe to re-run — all writes are upserts.
+
+```bash
+python tools/migrate_to_match_performances.py
 ```
 
-If a tournament is not entered on the first input field, it will default to LCC_Season_2
+### `tools/csv_to_match_json.py`
 
-## Results
-Once the program is run, an ```xlsx``` file containing the match and individual player stats will be available in the ```results``` directory labeled ```Stats_Report_{TODAYS DATE}```.  A JSON file will also be created for each match input for additional programmatic work.  I left some example files from 2024-04-12 in the ```results``` directory
+Converts an LCC stats CSV export into match JSON documents that can be inserted directly into MongoDB. Useful for matches where no Riot match ID is available.

app.py

@@ -0,0 +1,12 @@
+"""
+app.py
+------
+Entry point for running the LCC API locally.
+For production, the WSGI server targets ``lcc.main:app`` directly.
+"""
+from dotenv import load_dotenv
+from lcc.main import app
+
+if __name__ == '__main__':
+    load_dotenv(dotenv_path='.env', verbose=True, override=True)
+    app.run(debug=True, host='0.0.0.0')