Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
123 lines (96 loc) · 4.73 KB

CONTRIBUTING.md

File metadata and controls

123 lines (96 loc) · 4.73 KB
Raw

Contributing to Football Market Intelligence

First off, thank you for considering contributing to the Football Market Intelligence engine! It's people like you that make this tool better for everyone.

This document outlines the process for contributing to the repository, setting up your local environment, and our coding standards.

1. Local Development Setup

The easiest way to get the project running locally is via Docker Compose.

Prerequisites

Setup Steps

  1. Fork & Clone: Fork the repository on GitHub and clone it to your local machine.

    git clone https://github.com/Devathmaj/world-cup-analytics.git
cd world-cup-analytics

  2. Environment Variables: Navigate to the backend directory and copy the example environment file.

    cd backend
cp .env.example .env

    Open .env and fill in your API keys (e.g., your API_FOOTBALL_KEY). See the docs/Football_API_Setup.md for instructions on getting this key.

  3. Start the Stack: Return to the root directory and start the Docker containers.

    docker compose up -d

    This will spin up:

    • The PostgreSQL Database
    • The FastAPI Backend (available at http://localhost:8000)
    • The Next.js Frontend (available at http://localhost:3000)

2. Project Structure

Understanding the architecture will help you find where to make your changes. Please refer to docs/Project_overview.md and docs/API.md for more details:

  • /backend - The FastAPI Python application.
    • /app/api - REST endpoints and routing.
    • /app/db/models - SQLAlchemy database schemas (core, features, ml, etc).
    • /app/simulation - The Constrained Monte Carlo engine.
    • /ml - Machine learning pipelines, XGBoost/Logistic Regression training scripts.
    • /scripts - Background polling daemons (API-Football, Kalshi, Polymarket).
  • /frontend - The Next.js React application.
    • /app - Next.js App Router pages.
    • /components - Reusable UI components (Tailwind, Shadcn).
  • /data - Raw CSV and JSON files used for initial database seeding.
  • /docs - System documentation, architecture details, and ML model descriptions.

3. How to Contribute

Reporting Bugs

If you find a bug, please open an Issue on GitHub. Include:

  • A clear, descriptive title.
  • Steps to reproduce the bug.
  • Expected vs. actual behavior.
  • Logs or error messages if applicable.

Suggesting Features

We welcome new feature ideas! Open an Issue describing your proposed feature, why it would be valuable, and how it aligns with the project's goal of evaluating World Cup betting markets.

Submitting a Pull Request (PR)

  1. Branch out: Create a new branch from main for your feature or bugfix. 
    git checkout -b feature/your-feature-name
  2. Make your changes: Write your code, following the project's style guidelines.
  3. Commit: Write clear, concise commit messages. 
    git commit -m "Add new market intent parsing for group exact order"
  4. Push: Push your branch to your fork. 
    git push origin feature/your-feature-name
  5. Open a PR: Go to the original repository on GitHub and open a Pull Request. Describe your changes in detail and link any related issues.

4. Coding Standards

Python (Backend)

  • We use Python 3.12+.
  • Type Hinting: Use standard Python type hints across all functions and models.
  • Database: All database interactions should be asynchronous (AsyncSession) and use SQLAlchemy 2.0 syntax (select(), Mapped[]).
  • Linting: (If applicable) we recommend using flake8 or black for code formatting.

TypeScript / React (Frontend)

  • Use TypeScript strictly. Avoid any types.
  • Follow the functional component pattern with React Hooks.
  • Use Tailwind CSS for styling via the predefined className utilities.
  • Place reusable UI elements inside frontend/components/ui.

5. Database Migrations

If your contribution involves changing a database model in /backend/app/db/models/, you must generate an Alembic migration:

  1. Ensure the Docker containers are running.
  2. Execute the migration generation command inside the backend container: 
    docker compose exec backend alembic revision --autogenerate -m "Description of your changes"
  3. Review the generated script in /backend/alembic/versions/ to ensure it only contains the intended schema changes.
  4. Apply the migration locally to test it: 
    docker compose exec backend alembic upgrade head

Thank you again for contributing!