⚽ ScoutMe Backend

A Comprehensive Football Analytics Backend Application

📋 Table of Contents

Overview
Key Features
Tech Stack
Installation
Configuration
API Documentation
Database Schema
Development
Testing
Contributing
License

🎯 Overview

ScoutMe Backend is a powerful football analytics API built with Laravel, designed to provide comprehensive data and insights for football scouts, analysts, and enthusiasts. The platform offers detailed player statistics, match analytics, competition tracking, and subscription management capabilities.

What Makes ScoutMe Special?

📊 Detailed Player Analytics - Access comprehensive player statistics, performance metrics, and historical data
⚽ Match Statistics - Real-time match data with detailed team and player performance analysis
🏆 Competition Tracking - Monitor multiple competitions, seasons, and tournaments
🔍 Advanced Search - Powerful search functionality with filters for players, teams, and matches
👥 Scout Management - Dedicated tools for football scouts to track and manage players
💳 Subscription System - Flexible subscription plans using Laravel Cashier
🔐 Secure Authentication - Token-based authentication with Laravel Sanctum
📱 RESTful API - Clean, versioned API architecture

✨ Key Features

Player Management

Comprehensive player profiles with personal and performance data
Junior player tracking and development monitoring
Player position management with primary and secondary positions
Advanced filtering by position, nationality, team, and name
Full-text search capabilities using Laravel Scout

Match Analytics

Detailed match statistics and team performance metrics
Player-specific match statistics (attackers, goalkeepers, field players)
Match lineup and formation tracking
Historical match data and seasonal comparisons

Competition & Team Management

Multi-competition support with season tracking
Club and national team management
League standings and competition structures
Country and nationality tracking

Scout Features

Scout profiles with customizable notes
Player watchlists and tracking
Subscription-based access control
Dashboard with personalized insights

Subscription System

Multiple subscription tiers
Payment processing with Laravel Cashier
Subscription status tracking
Access level management

🛠 Tech Stack

Core Framework

Laravel 12.x - Modern PHP framework with elegant syntax
PHP 8.2+ - Latest PHP features and performance improvements

Key Packages

Laravel Sanctum - API token authentication
Laravel Scout - Full-text search
Laravel Cashier - Subscription billing
Spatie Laravel Permission - Role and permission management
Spatie Query Builder - Elegant API filtering and sorting

Development Tools

Laravel Telescope - Debug assistant
Laravel Pint - Code style fixer
Laravel Sail - Docker development environment
PHPUnit - Testing framework

Database

MySQL - Primary database
Redis - Caching and queue management (optional)

📦 Installation

Prerequisites

Before you begin, ensure you have the following installed:

PHP >= 8.2
Composer
MySQL >= 5.7 or MariaDB >= 10.3
Node.js & NPM (for asset compilation)

Step-by-Step Installation

Clone the repository

git clone https://github.com/MohanedM7md/ScoutMe-BE.git
cd ScoutMe-BE

Install PHP dependencies
```
composer install
```
Install Node dependencies
```
npm install
```

Configure environment

cp .env.example .env
php artisan key:generate

Configure database

Edit your .env file with your database credentials:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=scoutme
DB_USERNAME=your_username
DB_PASSWORD=your_password

Run migrations
```
php artisan migrate
```
Seed the database (optional)
```
php artisan db:seed
```
Create storage symlink
```
php artisan storage:link
```
Start the development server
```
php artisan serve
```

The API will be available at http://localhost:8000

Using Laravel Sail (Docker)

For a containerized development environment:

# Install dependencies
composer install

# Start Sail
./vendor/bin/sail up -d

# Run migrations
./vendor/bin/sail artisan migrate

# Access the application at http://localhost

⚙️ Configuration

Environment Variables

Key environment variables to configure:

# Application
APP_NAME=ScoutMe
APP_ENV=local
APP_DEBUG=true
APP_URL=http://localhost

# Database
DB_CONNECTION=mysql
DB_DATABASE=scoutme
DB_USERNAME=root
DB_PASSWORD=

# Session & Cache
SESSION_DRIVER=database
CACHE_STORE=database
QUEUE_CONNECTION=database

# Mail Configuration
MAIL_MAILER=smtp
MAIL_HOST=mailhog
MAIL_PORT=1025

# Payment (Laravel Cashier)
STRIPE_KEY=your_stripe_key
STRIPE_SECRET=your_stripe_secret

Permissions Setup

Run the following to set up proper permissions:

chmod -R 775 storage bootstrap/cache

🚀 API Documentation

Base URL

http://localhost:8000/api/v1

Authentication

The API uses Laravel Sanctum for authentication. Include the bearer token in the Authorization header:

Authorization: Bearer your-token-here

📘 Postman API Documentation

The full, interactive API documentation is available via Postman and includes:

All endpoints with request/response examples
Authentication setup
Query parameters and filters
Error responses

🔗 Postman Documentation:
https://documenter.getpostman.com/view/41344496/2sB3BKFofM

API Endpoints Overview

Authentication

POST   /api/v1/auth/register      # Register new user
POST   /api/v1/auth/login         # Login
POST   /api/v1/auth/logout        # Logout
GET    /api/v1/auth/user          # Get authenticated user

Players

GET    /api/v1/players             # List all players
GET    /api/v1/players/{id}        # Get player details
GET    /api/v1/players/search      # Search players
GET    /api/v1/players/stats/{id}  # Get player seasonal stats

Matches

GET    /api/v1/matches             # List all matches
GET    /api/v1/matches/{id}        # Get match details
GET    /api/v1/matches/{id}/stats  # Get match statistics
GET    /api/v1/matches/{id}/players # Get match players by team
GET    /api/v1/matches/{id}/player-stats # Get player stats by ID

Competitions

GET    /api/v1/competitions        # List competitions
GET    /api/v1/competitions/{id}   # Get competition details

Teams

GET    /api/v1/teams               # List teams
GET    /api/v1/teams/{id}          # Get team details

Subscriptions

GET    /api/v1/subscriptions       # List subscription plans
POST   /api/v1/subscriptions/subscribe # Subscribe to a plan

Scout

GET    /api/v1/scout/profile       # Get scout profile
PUT    /api/v1/scout/profile       # Update scout profile

Search

GET    /api/v1/search              # Global search endpoint

Dashboard

GET    /api/v1/dashboard           # Get dashboard data

Admin (Protected)

GET    /api/v1/admin/*             # Admin endpoints (role-based access)

Query Parameters

Most list endpoints support the following query parameters:

filter[column] - Filter by column value
sort - Sort by column (prefix with - for descending)
include - Include relationships
page[number] - Page number for pagination
page[size] - Items per page

Example:

GET /api/v1/players?filter[position]=Forward&sort=-name&include=team,nationality&page[number]=1&page[size]=20

🗄 Database Schema

Core Tables

Players

Personal information (name, nationality, birth date, height, weight)
Position and team associations
Player images

Matches

Match details (date, time, competition)
Team matchups
Final scores and match status

Match Statistics

Team-level statistics
Player-level statistics
Position-specific statistics (attackers, goalkeepers)

Clubs & Teams

Club information
Team rosters
Competition participation

Competitions

Competition details
Seasons
Competition structure

Subscriptions

Subscription plans
User subscriptions
Payment tracking

Scouts

Scout profiles
Notes and observations
User associations

💻 Development

Running the Development Server

# Standard development server
php artisan serve

# Or use the combined development command
composer dev

The composer dev command runs:

Laravel development server
Queue listener
Vite development server

Code Style

Format code using Laravel Pint:

./vendor/bin/pint

Database Management

# Create a new migration
php artisan make:migration create_table_name

# Run migrations
php artisan migrate

# Rollback migrations
php artisan migrate:rollback

# Fresh migration (drops all tables)
php artisan migrate:fresh

# Fresh migration with seeding
php artisan migrate:fresh --seed

Artisan Commands

# Clear application cache
php artisan cache:clear

# Clear configuration cache
php artisan config:clear

# Clear route cache
php artisan route:clear

# List all routes
php artisan route:list

# Run the queue worker
php artisan queue:work

# Monitor logs in real-time
php artisan pail

🧪 Testing

The project uses PHPUnit for testing.

Running Tests

# Run all tests
php artisan test

# Or use composer script
composer test

# Run specific test file
php artisan test tests/Feature/PlayerTest.php

# Run with coverage
php artisan test --coverage

Writing Tests

Tests are located in the tests/ directory:

tests/Feature/ - Feature tests (API endpoints, integration)
tests/Unit/ - Unit tests (models, services, helpers)

🤝 Contributing

We welcome contributions! Please follow these guidelines:

Fork the repository
Create a feature branch
```
git checkout -b feature/amazing-feature
```
Make your changes
Run tests
```
composer test
```
Format your code
```
./vendor/bin/pint
```

Commit your changes

git commit -m 'Add some amazing feature'

Push to the branch
```
git push origin feature/amazing-feature
```
Open a Pull Request

Name		Name	Last commit message	Last commit date
app		app
bootstrap		bootstrap
config		config
database		database
public		public
resources		resources
routes		routes
storage		storage
tests		tests
.editorconfig		.editorconfig
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
README.md		README.md
artisan		artisan
composer.json		composer.json
composer.lock		composer.lock
package.json		package.json
phpunit.xml		phpunit.xml
vite.config.js		vite.config.js

Latest commit

History

Folders and files

Repository files navigation

⚽ ScoutMe Backend

📋 Table of Contents

🎯 Overview

What Makes ScoutMe Special?

✨ Key Features

Player Management

Match Analytics

Competition & Team Management

Scout Features

Subscription System

🛠 Tech Stack

Core Framework

Key Packages

Development Tools

Database

📦 Installation

Prerequisites

Step-by-Step Installation

Using Laravel Sail (Docker)

⚙️ Configuration

Environment Variables

Permissions Setup

🚀 API Documentation

Base URL

Authentication

📘 Postman API Documentation

API Endpoints Overview

Authentication

Players

Matches

Competitions

Teams

Subscriptions

Scout

Search

Dashboard

Admin (Protected)

Query Parameters

🗄 Database Schema

Core Tables

Players

Matches

Match Statistics

Clubs & Teams

Competitions

Subscriptions

Scouts

💻 Development

Running the Development Server

Code Style

Database Management

Artisan Commands

🧪 Testing

Running Tests

Writing Tests

🤝 Contributing

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages