gitlytics 0.1.2__tar.gz → 0.1.4__tar.gz

{gitlytics-0.1.2/src/gitlytics.egg-info → gitlytics-0.1.4}/PKG-INFO

@@ -1,10 +1,13 @@
 Metadata-Version: 2.4
 Name: gitlytics
-Version: 0.1.2
+Version: 0.1.4
 Summary: Monitor and automate your GitHub repository traffic analytics.
-Author: Ameya Chopade
+Author-email: Ameya Chopade <ameyaccod171@gmail.com>
 License: Apache-2.0
-Project-URL: Homepage, https://github.com/ameyac11/gitlytics
+Project-URL: Homepage, https://gitlytics.dev
+Project-URL: Documentation, https://docs.gitlytics.dev
+Project-URL: Repository, https://github.com/ameyac11/gitlytics
+Project-URL: Bug Tracker, https://github.com/ameyac11/gitlytics/issues
 Keywords: github,traffic,analytics,automation,cli
 Classifier: Programming Language :: Python :: 3
 Classifier: License :: OSI Approved :: Apache Software License
@@ -12,17 +15,20 @@ Classifier: Operating System :: OS Independent
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: requests
-Requires-Dist: pandas
-Requires-Dist: python-dotenv
-Requires-Dist: croniter
+Requires-Dist: requests>=2.32.0
+Requires-Dist: pandas>=2.2.0
+Requires-Dist: python-dotenv>=1.0.1
+Requires-Dist: croniter>=2.0.0
 Provides-Extra: dashboard
-Requires-Dist: fastapi; extra == "dashboard"
-Requires-Dist: uvicorn; extra == "dashboard"
-Requires-Dist: python-multipart; extra == "dashboard"
+Requires-Dist: fastapi>=0.111.0; extra == "dashboard"
+Requires-Dist: uvicorn>=0.30.0; extra == "dashboard"
+Requires-Dist: python-multipart>=0.0.9; extra == "dashboard"
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0.0; extra == "dev"
 Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
+Requires-Dist: httpx>=0.27.0; extra == "dev"
+Requires-Dist: Faker>=20.0.0; extra == "dev"
+Requires-Dist: anyio[trio]>=4.0.0; extra == "dev"
 Dynamic: license-file
 
 <div align="center">
@@ -36,17 +42,26 @@ Dynamic: license-file
 [![React](https://img.shields.io/badge/UI-React-61dafb?logo=react)](https://react.dev/)
 [![FastAPI](https://img.shields.io/badge/Backend-FastAPI-009688?logo=fastapi)](https://fastapi.tiangolo.com/)
 [![Automation](https://img.shields.io/badge/Data%20Backup-Automation%20Tool-purple?logo=github-actions)](https://github.com/ameyac11/gitlytics-github-traffic-automation)
+[![Homepage](https://img.shields.io/badge/Homepage-gitlytics.dev-success)](https://gitlytics.dev)
+[![Live](https://img.shields.io/badge/Live%20Demo-dashboard.gitlytics.dev-success)](https://dashboard.gitlytics.dev)
+[![Docs](https://img.shields.io/badge/Docs-docs.gitlytics.dev-success)](https://docs.gitlytics.dev)
 
 **Beautiful GitHub traffic analytics for all your repositories — public and private.** <br/> Track views, clones, referrers, and popular paths indefinitely.
 
-Please consider giving this project a ⭐ if you find it helpful!
+✨ **[Try the live dashboard at dashboard.gitlytics.dev](https://dashboard.gitlytics.dev)** ✨  
+📚 **[Read the documentation at docs.gitlytics.dev](https://docs.gitlytics.dev)**
 
-</div>
+<br/>
 
----
+> **🐍 Native Python API**
+> 
+> You can import Gitlytics natively into your own Python applications to build custom integrations, run custom cron workflows, or serve the dashboard programmatically on your own cloud servers.
+> 
+> 📚 **[Read the Full API Documentation](https://docs.gitlytics.dev)**
 
-> **⚠️ NOTE: V0.1.2 ARCHITECTURE UPGRADE!** <br/>
-> Formerly `github-traffic-monitor`, we have officially rebranded to **`gitlytics`**! We completely migrated away from Streamlit. The dashboard is now a **React + Vite** SPA, powered by a **FastAPI** backend!
+Please consider giving this project a ⭐ if you find it helpful!
+
+</div>
 
 ---
 
@@ -62,7 +77,8 @@ Please consider giving this project a ⭐ if you find it helpful!
 
 ## 📌 Table of Contents
 
-- [🚨 The 14-Day Catch (And How We Fix It)](#the-14-day-catch-and-how-we-fix-it)
+- [🔗 The Gitlytics Ecosystem](#-the-gitlytics-ecosystem)
+- [🚨 The 14-Day Catch (And How We Fix It)](#-the-14-day-catch-and-how-we-fix-it)
 - [🛠️ Installation](#installation)
   - [🔑 Generating a GitHub Personal Access Token](#generating-a-github-personal-access-token)
 - [⌨️ The 3 Core CLI Commands](#the-3-core-cli-commands)
@@ -79,6 +95,15 @@ Please consider giving this project a ⭐ if you find it helpful!
 
 ---
 
+## 🔗 The Gitlytics Ecosystem
+
+The full Gitlytics ecosystem spans across a few repositories. If you are looking for the live web dashboard or the automation cron job, check out the links below:
+
+- 🌐 **[Gitlytics Web Ecosystem](https://github.com/ameyac11/gitlytics-deployement)**: The production homepage, React Dashboard, and VitePress documentation site.
+- ⚙️ **[Gitlytics Automation](https://github.com/ameyac11/gitlytics-github-traffic-automation)**: The GitHub Action companion tool that automates fetching and saving to defeat GitHub's 14-day traffic limit.
+
+---
+
 ## 🚨 The 14-Day Catch (And How We Fix It)
 
 > **⚠️ Did you know?** GitHub normally **only saves your repository traffic data for 14 days**. After two weeks, your valuable views and clones data is permanently deleted.
@@ -148,7 +173,7 @@ gitlytics dashboard
 
 You can import Gitlytics natively into your own Python applications to build custom integrations, run custom cron workflows, or serve the dashboard programmatically on your own cloud servers.
 
-📚 **[Read the Full API Documentation](docs/api_documentation.md)**
+📚 **[Read the Full API Documentation](https://docs.gitlytics.dev)**
 
 ### 1️⃣ `gitlytics.fetch_traffic()`
 Fetches the last 14 days of traffic data (views, clones, referrers, paths) for one or more repositories.
@@ -159,7 +184,7 @@ import gitlytics
 # Fetch traffic for all repositories accessible by the token
 df = gitlytics.fetch_traffic(
     token="ghp_your_token",
-    return_format="dataframe"  # Options: "dataframe" (Pandas), "timeseries" (React Chart-ready dict), or "raw" (JSON API payload)
+    return_format="dataframe"  # Options: "dataframe" (Pandas), "timeseries" (chart-ready dict), or "summary" (per-repo totals dict)
 )
 
 # Fetch traffic for a single specific repository and print the table to stdout
@@ -183,7 +208,7 @@ gitlytics.fetch_traffic(
 | `token` | `str` | *Required* | GitHub Personal Access Token with `repo` scope enabled. |
 | `repo_name` | `str` | `None` | Specific repository name (e.g. `"user/repo"`). If `None`, fetches all repositories. |
 | `print_table` | `bool` | `False` | If `True`, formats and prints a detailed ASCII traffic table to the console. |
-| `return_format` | `str` | `"dataframe"` | The format of returned data: `"dataframe"` (Pandas DataFrame), `"timeseries"`, or `"raw"`. |
+| `return_format` | `str` | `"dataframe"` | The format of returned data: `"dataframe"` (Pandas DataFrame), `"timeseries"` (chart-ready nested dict), or `"summary"` (per-repo totals dict). |
 | `save_file` | `str` | `None` | Optional. File path where the fetched data will be saved (CSV or JSON). |
 
 ---

gitlytics-0.1.2/PKG-INFO → gitlytics-0.1.4/README.md

@@ -1,30 +1,3 @@
-Metadata-Version: 2.4
-Name: gitlytics
-Version: 0.1.2
-Summary: Monitor and automate your GitHub repository traffic analytics.
-Author: Ameya Chopade
-License: Apache-2.0
-Project-URL: Homepage, https://github.com/ameyac11/gitlytics
-Keywords: github,traffic,analytics,automation,cli
-Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: Apache Software License
-Classifier: Operating System :: OS Independent
-Requires-Python: >=3.9
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: requests
-Requires-Dist: pandas
-Requires-Dist: python-dotenv
-Requires-Dist: croniter
-Provides-Extra: dashboard
-Requires-Dist: fastapi; extra == "dashboard"
-Requires-Dist: uvicorn; extra == "dashboard"
-Requires-Dist: python-multipart; extra == "dashboard"
-Provides-Extra: dev
-Requires-Dist: pytest>=8.0.0; extra == "dev"
-Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
-Dynamic: license-file
-
 <div align="center">
 
 # 📊 Gitlytics
@@ -36,17 +9,26 @@ Dynamic: license-file
 [![React](https://img.shields.io/badge/UI-React-61dafb?logo=react)](https://react.dev/)
 [![FastAPI](https://img.shields.io/badge/Backend-FastAPI-009688?logo=fastapi)](https://fastapi.tiangolo.com/)
 [![Automation](https://img.shields.io/badge/Data%20Backup-Automation%20Tool-purple?logo=github-actions)](https://github.com/ameyac11/gitlytics-github-traffic-automation)
+[![Homepage](https://img.shields.io/badge/Homepage-gitlytics.dev-success)](https://gitlytics.dev)
+[![Live](https://img.shields.io/badge/Live%20Demo-dashboard.gitlytics.dev-success)](https://dashboard.gitlytics.dev)
+[![Docs](https://img.shields.io/badge/Docs-docs.gitlytics.dev-success)](https://docs.gitlytics.dev)
 
 **Beautiful GitHub traffic analytics for all your repositories — public and private.** <br/> Track views, clones, referrers, and popular paths indefinitely.
 
-Please consider giving this project a ⭐ if you find it helpful!
+✨ **[Try the live dashboard at dashboard.gitlytics.dev](https://dashboard.gitlytics.dev)** ✨  
+📚 **[Read the documentation at docs.gitlytics.dev](https://docs.gitlytics.dev)**
 
-</div>
+<br/>
 
----
+> **🐍 Native Python API**
+> 
+> You can import Gitlytics natively into your own Python applications to build custom integrations, run custom cron workflows, or serve the dashboard programmatically on your own cloud servers.
+> 
+> 📚 **[Read the Full API Documentation](https://docs.gitlytics.dev)**
+
+Please consider giving this project a ⭐ if you find it helpful!
 
-> **⚠️ NOTE: V0.1.2 ARCHITECTURE UPGRADE!** <br/>
-> Formerly `github-traffic-monitor`, we have officially rebranded to **`gitlytics`**! We completely migrated away from Streamlit. The dashboard is now a **React + Vite** SPA, powered by a **FastAPI** backend!
+</div>
 
 ---
 
@@ -62,7 +44,8 @@ Please consider giving this project a ⭐ if you find it helpful!
 
 ## 📌 Table of Contents
 
-- [🚨 The 14-Day Catch (And How We Fix It)](#the-14-day-catch-and-how-we-fix-it)
+- [🔗 The Gitlytics Ecosystem](#-the-gitlytics-ecosystem)
+- [🚨 The 14-Day Catch (And How We Fix It)](#-the-14-day-catch-and-how-we-fix-it)
 - [🛠️ Installation](#installation)
   - [🔑 Generating a GitHub Personal Access Token](#generating-a-github-personal-access-token)
 - [⌨️ The 3 Core CLI Commands](#the-3-core-cli-commands)
@@ -79,6 +62,15 @@ Please consider giving this project a ⭐ if you find it helpful!
 
 ---
 
+## 🔗 The Gitlytics Ecosystem
+
+The full Gitlytics ecosystem spans across a few repositories. If you are looking for the live web dashboard or the automation cron job, check out the links below:
+
+- 🌐 **[Gitlytics Web Ecosystem](https://github.com/ameyac11/gitlytics-deployement)**: The production homepage, React Dashboard, and VitePress documentation site.
+- ⚙️ **[Gitlytics Automation](https://github.com/ameyac11/gitlytics-github-traffic-automation)**: The GitHub Action companion tool that automates fetching and saving to defeat GitHub's 14-day traffic limit.
+
+---
+
 ## 🚨 The 14-Day Catch (And How We Fix It)
 
 > **⚠️ Did you know?** GitHub normally **only saves your repository traffic data for 14 days**. After two weeks, your valuable views and clones data is permanently deleted.
@@ -148,7 +140,7 @@ gitlytics dashboard
 
 You can import Gitlytics natively into your own Python applications to build custom integrations, run custom cron workflows, or serve the dashboard programmatically on your own cloud servers.
 
-📚 **[Read the Full API Documentation](docs/api_documentation.md)**
+📚 **[Read the Full API Documentation](https://docs.gitlytics.dev)**
 
 ### 1️⃣ `gitlytics.fetch_traffic()`
 Fetches the last 14 days of traffic data (views, clones, referrers, paths) for one or more repositories.
@@ -159,7 +151,7 @@ import gitlytics
 # Fetch traffic for all repositories accessible by the token
 df = gitlytics.fetch_traffic(
     token="ghp_your_token",
-    return_format="dataframe"  # Options: "dataframe" (Pandas), "timeseries" (React Chart-ready dict), or "raw" (JSON API payload)
+    return_format="dataframe"  # Options: "dataframe" (Pandas), "timeseries" (chart-ready dict), or "summary" (per-repo totals dict)
 )
 
 # Fetch traffic for a single specific repository and print the table to stdout
@@ -183,7 +175,7 @@ gitlytics.fetch_traffic(
 | `token` | `str` | *Required* | GitHub Personal Access Token with `repo` scope enabled. |
 | `repo_name` | `str` | `None` | Specific repository name (e.g. `"user/repo"`). If `None`, fetches all repositories. |
 | `print_table` | `bool` | `False` | If `True`, formats and prints a detailed ASCII traffic table to the console. |
-| `return_format` | `str` | `"dataframe"` | The format of returned data: `"dataframe"` (Pandas DataFrame), `"timeseries"`, or `"raw"`. |
+| `return_format` | `str` | `"dataframe"` | The format of returned data: `"dataframe"` (Pandas DataFrame), `"timeseries"` (chart-ready nested dict), or `"summary"` (per-repo totals dict). |
 | `save_file` | `str` | `None` | Optional. File path where the fetched data will be saved (CSV or JSON). |
 
 ---

gitlytics-0.1.4/pyproject.toml

@@ -0,0 +1,75 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "gitlytics"
+version = "0.1.4"
+description = "Monitor and automate your GitHub repository traffic analytics."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "Apache-2.0" }
+authors = [
+    { name = "Ameya Chopade", email = "ameyaccod171@gmail.com" }
+]
+# Fix #20: Add version lower-bounds to prevent silent breakage on old environments.
+# These match the constraints already documented in requirements.txt.
+dependencies = [
+    "requests>=2.32.0",
+    "pandas>=2.2.0",
+    "python-dotenv>=1.0.1",
+    "croniter>=2.0.0"
+]
+keywords = [
+    "github",
+    "traffic",
+    "analytics",
+    "automation",
+    "cli"
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: Apache Software License",
+    "Operating System :: OS Independent",
+]
+
+[project.urls]
+Homepage = "https://gitlytics.dev"
+Documentation = "https://docs.gitlytics.dev"
+Repository = "https://github.com/ameyac11/gitlytics"
+"Bug Tracker" = "https://github.com/ameyac11/gitlytics/issues"
+
+[project.optional-dependencies]
+# Fix #20: dashboard extras are optional — base package works without them.
+# requirements.txt was including them as mandatory; that was wrong.
+dashboard = [
+    "fastapi>=0.111.0",
+    "uvicorn>=0.30.0",
+    "python-multipart>=0.0.9"
+]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-cov>=5.0.0",
+    "httpx>=0.27.0",      # required by FastAPI TestClient (used in test_api.py)
+    "Faker>=20.0.0",      # used by pytest-faker plugin for generating test data
+    "anyio[trio]>=4.0.0"  # async test support
+]
+
+
+[project.scripts]
+gitlytics = "gitlytics.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["gitlytics*"]
+
+[tool.setuptools.package-data]
+"gitlytics" = ["static/**/*", "static/*"]
+
+[tool.pytest.ini_options]
+# Only collect files that match the offline test naming convention.
+# live_*.py scripts are excluded — they need a real GitHub token.
+testpaths = ["tests"]
+python_files  = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]

gitlytics-0.1.4/src/gitlytics/__init__.py

@@ -0,0 +1,140 @@
+"""
+gitlytics/__init__.py
+The public API for the gitlytics package.
+"""
+import os
+import logging
+import json
+
+# Single source of truth for the package version.
+# Mirrors the version in pyproject.toml — keep them in sync.
+__version__ = "0.1.4"
+
+# Import the internal building blocks — users never call these directly
+from .core import fetch_traffic_data, print_repo_table
+from .automation import run_sync
+from .process import build_json_payload
+
+# Set up a silent logger so gitlytics never messes with your app's logging
+logger = logging.getLogger(__name__)
+logger.addHandler(logging.NullHandler())
+
+
+def fetch_traffic(token: str, repo_name=None, print_table: bool = False, return_format: str = "dataframe", save_file: str = None):
+    """
+    Fetches the last 14 days of traffic data for one or all repositories.
+
+    Args:
+        token: GitHub Personal Access Token with `repo` scope.
+        repo_name: Specific repo name (e.g. ``"user/repo"``) or list of names.
+            If ``None``, fetches all repositories accessible by the token.
+        print_table: If ``True``, prints an ASCII summary table to stdout.
+        return_format: Shape of the returned data. One of:
+            ``"dataframe"`` (default) — returns a ``pandas.DataFrame``.
+            ``"timeseries"`` — returns a nested JSON-serialisable dict.
+            ``"summary"`` — returns a per-repo totals dict.
+        save_file: Optional path to save the output. Extension determines
+            format: ``.json`` writes JSON, anything else writes CSV.
+
+    Returns:
+        A ``pandas.DataFrame`` when ``return_format="dataframe"``, otherwise
+        a ``dict`` matching the requested format.
+    """
+    # Hit the GitHub API and get back a tidy DataFrame (one row per day per repo)
+    df = fetch_traffic_data(token, repo_name)
+
+    # Print the ASCII table to the console if the user asked for it
+    if print_table:
+        print_repo_table(df)
+
+    # --- dataframe mode: just return the raw DataFrame, optionally save it ---
+    if return_format == "dataframe":
+        if save_file:
+            if save_file.endswith(".json"):
+                # Save as a chart-ready JSON file
+                payload = build_json_payload(df, return_format="timeseries", export_public_only=True)
+                with open(save_file, "w", encoding="utf-8") as f:
+                    json.dump(payload, f, indent=2)
+            else:
+                # Save as a standard CSV file
+                df.to_csv(save_file, index=False)
+        return df
+
+    # Reject anything that isn't a known format before doing more work
+    valid_formats = {"timeseries", "summary"}
+    if return_format not in valid_formats:
+        raise ValueError(
+            f"Invalid return_format={return_format!r}. "
+            f"Choose one of: 'dataframe', 'timeseries', 'summary'."
+        )
+
+    # Build the JSON-serialisable payload in the requested shape
+    payload = build_json_payload(df, return_format=return_format, export_public_only=False)
+
+    # Save to disk if the user gave us a file path
+    if save_file:
+        with open(save_file, "w", encoding="utf-8") as f:
+            json.dump(payload, f, indent=2)
+
+    return payload
+
+
+def sync(token: str, repo_name=None, data_dir: str = "./data", output_mode: str = "monthly", schedule_cron: str = None, export_json: str = None, export_public_only: bool = True):
+    """
+    Fetches data and appends it to a local CSV database, optionally running as a permanent background daemon.
+
+    Args:
+        token: GitHub Personal Access Token.
+        repo_name: Specific repository name(s) to sync. If ``None``, syncs all.
+        data_dir: Directory where CSV files are stored.
+        output_mode: ``"monthly"`` (``traffic_YYYY-MM.csv``) or ``"yearly"`` (``traffic_YYYY.csv``).
+        schedule_cron: Standard cron expression (e.g. ``"0 23 * * *"``). If set,
+            runs an infinite scheduler loop.
+        export_json: Path to export the merged historical database as a JSON file.
+        export_public_only: If ``True`` (default), strips private repos from the
+            exported JSON — acts as a security firewall.
+    """
+    # Hand off to the automation engine — it handles deduplication and schema migration
+    run_sync(
+        token=token,
+        repo_names=repo_name,
+        data_dir=data_dir,
+        output_mode=output_mode,
+        schedule_cron=schedule_cron,
+        export_json=export_json,
+        export_public_only=export_public_only
+    )
+
+
+def serve_dashboard(host: str = "127.0.0.1", port: int = 8000, token: str = None, data_dir: str = None):
+    """
+    Starts the React + FastAPI dashboard server.
+
+    ``uvicorn`` and ``fastapi`` are optional dependencies installed via::
+
+        pip install "gitlytics[dashboard]"
+
+    Args:
+        host: Host IP to bind. Use ``"0.0.0.0"`` to listen on all interfaces.
+        port: Port number (default ``8000``).
+        token: Optional GitHub token — pre-authenticates the dashboard session.
+        data_dir: Optional path to the historical CSV database directory.
+    """
+    # Only import uvicorn when the user actually calls serve_dashboard,
+    # so the base `pip install gitlytics` doesn't crash without it
+    try:
+        import uvicorn
+    except ImportError:
+        raise ImportError(
+            "The dashboard requires additional dependencies. "
+            "Install them with: pip install \"gitlytics[dashboard]\""
+        )
+
+    # Pass the token and data folder to the FastAPI app via environment variables
+    if token:
+        os.environ["GITLYTICS_TOKEN"] = token
+    if data_dir:
+        os.environ["GITLYTICS_DATA_DIR"] = os.path.abspath(data_dir)
+
+    # Start the web server — it won't return until the user presses Ctrl+C
+    uvicorn.run("gitlytics.api:app", host=host, port=port, reload=False)

gitlytics-0.1.4/src/gitlytics/__main__.py

@@ -0,0 +1,9 @@
+"""
+gitlytics/__main__.py
+Makes `python -m gitlytics` work identically to the `gitlytics` console command.
+This is the entry point Python calls when the package is run with -m.
+"""
+from gitlytics.cli import main
+
+# Run the CLI when invoked as `python -m gitlytics`
+main()

gitlytics-0.1.4/src/gitlytics/api.py

@@ -0,0 +1,177 @@
+"""
+gitlytics/api.py
+Powers the FastAPI backend — serves traffic data and the React dashboard to the browser.
+"""
+import logging
+import os
+from pathlib import Path
+
+import pandas as pd
+from fastapi import FastAPI, HTTPException, Body, File, UploadFile
+from fastapi.responses import FileResponse, JSONResponse
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.staticfiles import StaticFiles
+
+from gitlytics.core import validate_token, get_user_profile, fetch_traffic_data
+from gitlytics.process import process_uploaded_csv, build_react_payload
+
+logger = logging.getLogger(__name__)
+
+app = FastAPI(title="GitHub Traffic API")
+
+# Only allow requests from localhost — this dashboard is never deployed publicly
+_ALLOWED_ORIGINS = [
+    "http://localhost",
+    "http://localhost:3000",
+    "http://localhost:5173",
+    "http://localhost:8000",
+    "http://127.0.0.1",
+    "http://127.0.0.1:3000",
+    "http://127.0.0.1:5173",
+    "http://127.0.0.1:8000",
+]
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=_ALLOWED_ORIGINS,
+    allow_credentials=True,
+    allow_methods=["GET", "POST"],
+    allow_headers=["Content-Type"],
+)
+
+
+def _get_token(token: str = None) -> str:
+    # Use the token from the request body, or fall back to the one set in the environment
+    return token or os.environ.get("GITLYTICS_TOKEN")
+
+
+@app.get("/api/config")
+def get_config():
+    # Lets the frontend know if it's running in headless/TV mode with a pre-set token
+    return {
+        "has_token": bool(os.environ.get("GITLYTICS_TOKEN")),
+        "has_data_dir": bool(os.environ.get("GITLYTICS_DATA_DIR"))
+    }
+
+
+@app.post("/api/auth")
+def auth(token: str = Body("", embed=True)):
+    # Validate the token and return the user's GitHub profile info
+    active_token = _get_token(token)
+    if not active_token:
+        raise HTTPException(status_code=401, detail="No token provided and no environment token found.")
+
+    ok, username = validate_token(active_token)
+    if not ok:
+        # Log a warning without echoing the token value into logs
+        logger.warning("Authentication attempt failed for a provided token.")
+        raise HTTPException(status_code=401, detail=username)
+
+    # Fetch the real display name and avatar URL — validate_token only gives us the login
+    profile = get_user_profile(active_token)
+
+    return {
+        "authenticated": True,
+        "username": profile["login"] or username,
+        "name": profile["name"] or username,        # Real display name, e.g. "Ameya Chopade"
+        "avatar_url": profile["avatar_url"],         # Real GitHub avatar URL
+    }
+
+
+@app.post("/api/traffic")
+def get_traffic(token: str = Body("", embed=True)):
+    # Serve traffic data — either from the historical CSV database or live from GitHub
+    active_token = _get_token(token)
+    if not active_token:
+        raise HTTPException(status_code=401, detail="No token provided")
+
+    ok, _ = validate_token(active_token)
+    if not ok:
+        raise HTTPException(status_code=401, detail="Invalid token")
+
+    data_dir = os.environ.get("GITLYTICS_DATA_DIR")
+    if data_dir:
+        # Load from the historical CSV database (headless/TV mode)
+        data_dir_path = Path(data_dir)
+        csv_files = list(data_dir_path.glob("traffic_*.csv")) if data_dir_path.exists() else []
+        dfs = []
+        for f in csv_files:
+            try:
+                dfs.append(pd.read_csv(f))
+            except Exception as exc:
+                logger.warning(f"Skipping unreadable CSV '{f}': {exc}")
+        if dfs:
+            df = pd.concat(dfs, ignore_index=True)
+            # Clean up any duplicate day-repo rows that crept in somehow
+            df = df.drop_duplicates(subset=["date", "repository"], keep="last")
+        else:
+            # No CSVs found — fall through to a live fetch
+            df = fetch_traffic_data(active_token)
+    else:
+        # Default: hit GitHub and get the live 14-day window
+        df = fetch_traffic_data(active_token)
+
+    # Replace any infinity or NaN values before JSON serialisation
+    df = df.replace([float('inf'), float('-inf')], None).where(pd.notnull(df), None)
+
+    # Transform the DataFrame into the array of objects the React app expects
+    payload = build_react_payload(df)
+    return payload
+
+
+@app.post("/api/upload-csv")
+def upload_csv(file: UploadFile = File(...)):
+    # Accept a user-uploaded CSV and convert it to the same format as the API response
+    try:
+        df = process_uploaded_csv(file.file)
+        df = df.replace([float('inf'), float('-inf')], None).where(pd.notnull(df), None)
+        payload = build_react_payload(df)
+        return payload
+    except Exception as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+# ── Static file serving ───────────────────────────────────────────────────────
+# The React build output lands in gitlytics/static/ after `npm run build`
+frontend_dir = Path(__file__).parent / "static"
+
+
+@app.get("/")
+def serve_index():
+    # Serve the React app's index.html for the root URL
+    index_file = frontend_dir / "index.html"
+    if index_file.exists():
+        return FileResponse(index_file)
+    return JSONResponse(
+        status_code=503,
+        content={"error": "Dashboard not found. Run 'npm run build' in the dashboard directory."}
+    )
+
+
+@app.get("/{full_path:path}")
+def serve_spa_fallback(full_path: str):
+    """
+    SPA catch-all — any URL that doesn't match an API route returns index.html
+    so React Router can handle client-side navigation on hard refresh.
+    Real static assets (JS/CSS) are served by the StaticFiles mount first.
+    """
+    # Serve the actual file if it exists (e.g. a JS or CSS asset)
+    asset_file = frontend_dir / full_path
+    if asset_file.exists() and asset_file.is_file():
+        return FileResponse(asset_file)
+
+    # For everything else (like /repos/my-repo), hand control to React Router
+    index_file = frontend_dir / "index.html"
+    if index_file.exists():
+        return FileResponse(index_file)
+
+    return JSONResponse(
+        status_code=503,
+        content={"error": "Dashboard not found. Run 'npm run build' in the dashboard directory."}
+    )
+
+
+# Mount the /assets directory for compiled JS and CSS — must come after route definitions
+assets_dir = frontend_dir / "assets"
+if assets_dir.exists():
+    app.mount("/assets", StaticFiles(directory=assets_dir), name="assets")