MATCHPULSE

MATCHPULSE is a real-time, autonomous AI-powered football media generation platform. It actively monitors live global football matches, dynamically generates hyper-realistic, cinematic 9:16 posters for key match events using AI, and securely publishes them directly to Instagram Stories.

Designed with a premium Bauhaus-inspired, Constructivist UI, MATCHPULSE operates as a fully-featured SaaS dashboard, allowing creators, fan pages, and sports media teams to cover live matches with elite, UEFA-quality graphics in seconds.

---

How It Works

1. Secure Meta OAuth Authentication: Users securely authenticate their Instagram Professional accounts via the official Facebook/Meta OAuth flow. Next.js Middleware ensures that the live dashboard is strictly protected and only accessible to authenticated users.
2. Live Intelligence Scanning: The Python FastAPI backend continuously polls the Sofascore API (using curl_cffi to bypass Cloudflare) to detect live football matches globally.
3. Real-Time WebSockets: Once a match is selected, the frontend connects via WebSockets to stream a live timeline of key match events (Goals, Red/Yellow Cards, Substitutions, Half Time, and Full Time).
4. Dynamic Prompt Engineering: Clicking on a timeline event automatically triggers an advanced AI prompt generation engine. The engine calculates the historical score at that exact minute, evaluates the context, and produces a highly detailed cinematic prompt.
5. Generative AI (FLUX): The custom prompt is sent to the HuggingFace Inference API utilizing the FLUX.1-schnell model. It returns a photorealistic, 9:16 vertical poster styled like a premium sports campaign. The image is cached in Redis.
6. Official Instagram Graph API: Upon approval, the backend utilizes the official Meta Graph API to autonomously publish the generated poster directly to the user's Instagram Story.

---

Tech Stack

Frontend (Command Center)

• Framework: Next.js (React) App Router
• Security: Next.js Edge Middleware for route protection and IDOR prevention
• Styling: TailwindCSS v4 with custom CSS variables
• Animations: Framer Motion for buttery-smooth timeline UI transitions
• Design Language: Bauhaus / Constructivism (Hard shadows, geometric borders, bold typography, strict primary color palette of Red, Blue, and Yellow).

Backend (Data & Operations)

• Framework: FastAPI (Python)
• Real-time Comm: WebSockets for live timeline broadcasting
• Storage: Redis for OAuth token state management and temporary Base64 image caching
• Instagram Integration: Official Meta Graph API via OAuth 2.0
• Scraping: curl_cffi to impersonate Chrome TLS fingerprints for sports data extraction

AI & Media

• Image Generator: FLUX.1-schnell via HuggingFace Inference API

---

Setup & Installation

Prerequisites

• Python 3.10+
• Node.js 18+
• Redis Server (running locally or via cloud)
• Render account (for hosting the backend and exposing it to Meta's servers)
• Meta Developer App (with Instagram Graph API access)

Environment Variables

Create a .env file in the backend/ directory:

REDIS_URL=redis://localhost:6379/0
HF_TOKEN=your_huggingface_api_token

# Meta OAuth Configuration
META_CLIENT_ID=your_facebook_app_id
META_CLIENT_SECRET=your_facebook_app_secret
META_REDIRECT_URI=http://localhost:3000/callback
SCRAPER_API_KEY=your_scraper_api_key

Running the Backend

# 1. Start the backend server
cd backend
python -m venv venv
source venv/bin/activate  # (or venv\Scripts\activate on Windows)
pip install -r requirements.txt
uvicorn api:app --host 0.0.0.0 --port 8000 --reload

# 2. Deploy to Render
# Connect your GitHub repository to Render to automatically deploy the FastAPI service and Redis database.

Running the Frontend

cd frontend
npm install
npm run dev

Navigate to http://localhost:3000 to access the SaaS Landing Page.

---

Architecture Highlights

• Official Meta Integration: Replaced unofficial, fragile scraping libraries with Meta's robust Graph API. Token exchange, 60-day long-lived access tokens, and page lookups are entirely managed by the backend.
• Component-Driven Next.js Architecture: The frontend employs a strict component-driven architecture, separating the marketing landing page from the secure /matches dashboard.
• Edge Routing Security: Next.js Middleware acts as a gatekeeper, instantly validating Instagram authentication status before granting access to dashboard routes.
• Smart Timeline Filtering: The backend intelligently filters out premature period incidents provided by data providers, ensuring "Half Time" and "Full Time" are only visible exactly when the match status legitimately changes.

---

👨‍💻 Developed By

Ashin Sabu Mathew

• Portfolio | GitHub