ProStaff API

Ruby on Rails API for the ProStaff.gg esports team management platform.

Key Features (Click to show details)

• JWT Authentication with refresh tokens and token blacklisting
• Interactive Swagger Documentation (107 endpoints documented)
• Riot Games API Integration for automatic match import and player sync
• Advanced Analytics (KDA trends, champion pools, vision control, etc.)
• Scouting System with talent discovery and watchlist management
• VOD Review System with timestamp annotations
• ️ Schedule Management for matches, scrims, and team events
• Goal Tracking for team and player performance objectives
• Background Jobs with Sidekiq for async processing
• ️ Security Hardened (OWASP Top 10, Brakeman, ZAP tested)
• High Performance (p95: ~500ms, with cache: ~50ms)
• ️ Modular Monolith architecture for scalability

Table of Contents

• Quick Start
• Technology Stack
• Architecture
• Setup
• Development Tools
• API Documentation
• Testing
• Performance & Load Testing
• Security
• Deployment
• Contributing
• License

Quick Start (Click to show details)

Option 1: With Docker (Recommended)

# Start all services (API, PostgreSQL, Redis, Sidekiq)
docker compose up -d

# Create test user
docker exec prostaff-api-api-1 rails runner scripts/create_test_user.rb

# Get JWT token for testing
./scripts/get-token.sh

# Access API docs
open http://localhost:3333/api-docs

# Run smoke tests
./load_tests/run-tests.sh smoke local

# Run security scan
./security_tests/scripts/brakeman-scan.sh

Option 2: Without Docker (Local Development)

# Install dependencies
bundle install

# Generate secrets
./scripts/generate_secrets.sh  # Copy output to .env

# Setup database
rails db:create db:migrate db:seed

# Start Redis (in separate terminal)
redis-server

# Start Sidekiq (in separate terminal)
bundle exec sidekiq

# Start Rails server
rails server -p 3333

# Get JWT token for testing
./scripts/get-token.sh

# Access API docs
open http://localhost:3333/api-docs

API will be available at: http://localhost:3333 Swagger Docs: http://localhost:3333/api-docs

Technology Stack

• Ruby: 3.4.5
• Rails: 7.2.0 (API-only mode)
• Database: PostgreSQL 14+
• Authentication: JWT (with refresh tokens)
• Background Jobs: Sidekiq
• Caching: Redis (port 6380)
• API Documentation: Swagger/OpenAPI 3.0 (rswag)
• Testing: RSpec, Integration Specs, k6, OWASP ZAP
• Authorization: Pundit
• Serialization: Blueprinter

Architecture

This API follows a modular monolith architecture with the following modules:

• authentication - User authentication and authorization
• dashboard - Dashboard statistics and metrics
• players - Player management and statistics
• scouting - Player scouting and talent discovery
• analytics - Performance analytics and reporting
• matches - Match data and statistics
• schedules - Event and schedule management
• vod_reviews - Video review and timestamp management
• team_goals - Goal setting and tracking
• riot_integration - Riot Games API integration

Architecture Diagram

graph TB
    subgraph "Client Layer"
        Client[Frontend Application]
    end

    subgraph "API Gateway"
        Router[Rails Router]
        CORS[CORS Middleware]
        RateLimit[Rate Limiting]
        Auth[Authentication Middleware]
    end

    subgraph "Application Layer - Modular Monolith"
        subgraph "Authentication Module"
            AuthController[Auth Controller]
            JWTService[JWT Service]
            UserModel[User Model]
        end
        subgraph "Analytics Module"
            AnalyticsController[Analytics Controller]
            PerformanceService[Performance Service]
            KDAService[KDA Trend Service]
        end
        subgraph "Competitive Module"
            CompetitiveController[Competitive Controller]
        end
        subgraph "Dashboard Module"
            DashboardController[Dashboard Controller]
            DashStats[Statistics Service]
        end
        subgraph "Matches Module"
            MatchesController[Matches Controller]
            MatchModel[Match Model]
            PlayerMatchStats[Player Match Stats Model]
        end
        subgraph "Players Module"
            PlayersController[Players Controller]
            PlayerModel[Player Model]
            ChampionPool[Champion Pool Model]
        end
        subgraph "Riot Integration Module"
            RiotIntegrationController[Riot Integration Controller]
            RiotService[Riot API Service]
            RiotSync[Sync Service]
        end
        subgraph "Schedules Module"
            SchedulesController[Schedules Controller]
            ScheduleModel[Schedule Model]
        end
        subgraph "Scouting Module"
            ScoutingController[Scouting Controller]
            ScoutingTarget[Scouting Target Model]
            Watchlist[Watchlist Service]
        end
        subgraph "Scrims Module"
            ScrimsController[Scrims Controller]
        end
        subgraph "Team Goals Module"
            GoalsController[Team Goals Controller]
            GoalModel[Team Goal Model]
        end
        subgraph "VOD Reviews Module"
            VODController[VOD Reviews Controller]
            VODModel[VOD Review Model]
            TimestampModel[Timestamp Model]
        end
    end

    subgraph "Data Layer"
        PostgreSQL[(PostgreSQL Database)]
        Redis[(Redis Cache)]
    end

    subgraph "Background Jobs"
        Sidekiq[Sidekiq Workers]
        JobQueue[Job Queue]
    end

    subgraph "External Services"
        RiotAPI[Riot Games API]
    end

    %% Conexões
    Client -->|HTTP/JSON| CORS
    CORS --> RateLimit
    RateLimit --> Auth
    Auth --> Router
    
    Router --> AuthController
    Router --> AnalyticsController
    Router --> CompetitiveController
    Router --> DashboardController
    Router --> MatchesController
    Router --> PlayersController
    Router --> RiotIntegrationController
    Router --> SchedulesController
    Router --> ScoutingController
    Router --> ScrimsController
    Router --> GoalsController
    Router --> VODController

    AuthController --> JWTService --> Redis
    AuthController --> UserModel
    AnalyticsController --> PerformanceService --> Redis
    AnalyticsController --> KDAService
    DashboardController --> DashStats --> Redis
    MatchesController --> MatchModel --> PlayerMatchStats
    PlayersController --> PlayerModel --> ChampionPool
    ScoutingController --> ScoutingTarget
    ScoutingController --> Watchlist
    SchedulesController --> ScheduleModel
    GoalsController --> GoalModel
    VODController --> VODModel --> TimestampModel

    %% Conexões para PostgreSQL (modelos adicionais)
    AuditLogModel[Audit Log Model] --> PostgreSQL
    ChampionPool --> PostgreSQL
    CompetitiveMatchModel[Competitive Match Model] --> PostgreSQL
    MatchModel --> PostgreSQL
    NotificationModel[Notification Model] --> PostgreSQL
    OpponentTeamModel[Opponent Team Model] --> PostgreSQL
    OrganizationModel[Organization Model] --> PostgreSQL
    PasswordResetTokenModel[Password Reset Token Model] --> PostgreSQL
    PlayerModel --> PostgreSQL
    PlayerMatchStats --> PostgreSQL
    ScheduleModel --> PostgreSQL
    ScoutingTarget --> PostgreSQL
    ScrimModel[Scrim Model] --> PostgreSQL
    GoalModel --> PostgreSQL
    TokenBlacklistModel[Token Blacklist Model] --> PostgreSQL
    UserModel --> PostgreSQL
    VODModel --> PostgreSQL
    TimestampModel --> PostgreSQL

    %% Integrações com Riot e Jobs
    PlayersController --> RiotService
    MatchesController --> RiotService
    ScoutingController --> RiotService
    RiotService --> RiotAPI
    RiotService --> Sidekiq --> JobQueue --> Redis

    %% Estilos
    style Client fill:#e1f5ff
    style PostgreSQL fill:#336791
    style Redis fill:#d82c20
    style RiotAPI fill:#eb0029
    style Sidekiq fill:#b1003e

Loading

Key Architecture Principles:

1. Modular Monolith: Each module is self-contained with its own controllers, models, and services
2. API-Only: Rails configured in API mode for JSON responses
3. JWT Authentication: Stateless authentication using JWT tokens
4. Background Processing: Long-running tasks handled by Sidekiq
5. Caching: Redis used for session management and performance optimization
6. External Integration: Riot Games API integration for real-time data
7. Rate Limiting: Rack::Attack for API rate limiting
8. CORS: Configured for cross-origin requests from frontend

Setup

Prerequisites

• Ruby 3.2+
• PostgreSQL 14+
• Redis 6+

Installation

1. Clone the repository:

git clone <repository-url>
cd prostaff-api

2. Install dependencies:

bundle install

3. Setup environment variables:

cp .env.example .env

Edit .env with your configuration:

• Database credentials
• JWT secret key
• Riot API key
• Redis URL
• CORS origins

4. Setup the database:

rails db:create
rails db:migrate
rails db:seed

5. Start the services:

Start Redis:

redis-server

Start Sidekiq (in another terminal):

bundle exec sidekiq

Start the Rails server:

rails server

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

Development Tools

Generate Secrets

Generate secure secrets for your .env file:

./scripts/generate_secrets.sh

This will generate:

• SECRET_KEY_BASE - Rails secret key
• JWT_SECRET_KEY - JWT signing key

Get JWT Token (for API testing)

Generate a JWT token for testing the API:

./scripts/get-token.sh

This will:

1. Create or find a test user ([email protected])
2. Generate a valid JWT token
3. Show instructions on how to use it

Quick usage:

# Export to environment variable
export BEARER_TOKEN=$(./scripts/get-token.sh | grep -oP 'eyJ[A-Za-z0-9_-]*\.[A-Za-z0-9_-]*\.[A-Za-z0-9_-]*')

# Use in curl
curl -H "Authorization: Bearer $BEARER_TOKEN" http://localhost:3333/api/v1/players

Custom credentials:

TEST_EMAIL="[email protected]" TEST_PASSWORD="MyPass123!" ./scripts/get-token.sh

📚 API Documentation (Click to show details)

Interactive Documentation (Swagger UI)

The API provides interactive documentation powered by Swagger/OpenAPI 3.0:

Access the docs:

http://localhost:3333/api-docs

Features:

• ✅ Try out endpoints directly from the browser
• ✅ See request/response schemas
• ✅ Authentication support (Bearer token)
• ✅ Complete parameter documentation
• ✅ Example requests and responses

Generating/Updating Documentation

The Swagger documentation is automatically generated from RSpec integration tests:

# Run integration specs and generate Swagger docs
bundle exec rake rswag:specs:swaggerize

# Or run specs individually
bundle exec rspec spec/integration/

The generated documentation file is located at swagger/v1/swagger.yaml.

Base URL

http://localhost:3333/api/v1

Authentication

All endpoints (except auth endpoints) require a Bearer token in the Authorization header:

Authorization: Bearer <your-jwt-token>

Token Details:

• Access Token: Expires in 24 hours (configurable via JWT_EXPIRATION_HOURS)
• Refresh Token: Expires in 7 days
• Token Type: Bearer (JWT)

Getting a token:

# Option 1: Use the script
./scripts/get-token.sh

# Option 2: Login via API
curl -X POST http://localhost:3333/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"Test123!@#"}'

Refreshing a token:

curl -X POST http://localhost:3333/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token":"your-refresh-token"}'

Authentication Endpoints

• POST /auth/register - Register new organization and admin user
• POST /auth/login - Login user
• POST /auth/refresh - Refresh JWT token
• POST /auth/logout - Logout user
• POST /auth/forgot-password - Request password reset
• POST /auth/reset-password - Reset password
• GET /auth/me - Get current user info

Core Endpoints

Dashboard

• GET /dashboard - Get complete dashboard data
• GET /dashboard/stats - Get quick stats
• GET /dashboard/activities - Get recent activities
• GET /dashboard/schedule - Get upcoming schedule

Players

• GET /players - List players
• GET /players/:id - Get player details
• POST /players - Create player
• PATCH /players/:id - Update player
• DELETE /players/:id - Delete player
• GET /players/stats - Get roster statistics
• POST /players/import - Import player from Riot API

Matches

• GET /matches - List matches
• GET /matches/:id - Get match details
• POST /matches - Create match
• POST /matches/import - Import match from Riot API

Scouting

• GET /scouting/players - List scouting targets
• GET /scouting/regions - Get available regions
• POST /scouting/players - Add scouting target

Analytics

• GET /analytics/performance - Team performance analytics
• GET /analytics/team-comparison - Compare all players
• GET /analytics/champions/:player_id - Champion pool statistics
• GET /analytics/kda-trend/:player_id - KDA trend over time
• GET /analytics/laning/:player_id - Laning phase performance
• GET /analytics/teamfights/:player_id - Teamfight performance
• GET /analytics/vision/:player_id - Vision control statistics

Schedules

• GET /schedules - List all scheduled events
• GET /schedules/:id - Get schedule details
• POST /schedules - Create new event
• PATCH /schedules/:id - Update event
• DELETE /schedules/:id - Delete event

Team Goals

• GET /team-goals - List all goals
• GET /team-goals/:id - Get goal details
• POST /team-goals - Create new goal
• PATCH /team-goals/:id - Update goal progress
• DELETE /team-goals/:id - Delete goal

VOD Reviews

• GET /vod-reviews - List VOD reviews
• GET /vod-reviews/:id - Get review details
• POST /vod-reviews - Create new review
• PATCH /vod-reviews/:id - Update review
• DELETE /vod-reviews/:id - Delete review
• GET /vod-reviews/:id/timestamps - List timestamps
• POST /vod-reviews/:id/timestamps - Create timestamp
• PATCH /vod-timestamps/:id - Update timestamp
• DELETE /vod-timestamps/:id - Delete timestamp

Riot Data

• GET /riot-data/champions - Get champions ID map
• GET /riot-data/champions/:key - Get champion details
• GET /riot-data/all-champions - Get all champions data
• GET /riot-data/items - Get all items
• GET /riot-data/summoner-spells - Get summoner spells
• GET /riot-data/version - Get current Data Dragon version
• POST /riot-data/clear-cache - Clear Data Dragon cache (owner only)
• POST /riot-data/update-cache - Update Data Dragon cache (owner only)

Riot Integration

• GET /riot-integration/sync-status - Get sync status for all players

For complete endpoint documentation with request/response examples, visit /api-docs

🧪 Testing

Unit & Request Tests

Run the complete test suite:

bundle exec rspec

Run specific test types:

# Unit tests (models, services)
bundle exec rspec spec/models
bundle exec rspec spec/services

# Request tests (controllers)
bundle exec rspec spec/requests

# Integration tests (Swagger documentation)
bundle exec rspec spec/integration

Integration Tests (Swagger Documentation)

Integration tests serve dual purpose:

1. Test API endpoints with real HTTP requests
2. Generate Swagger documentation automatically

# Run integration tests and generate Swagger docs
bundle exec rake rswag:specs:swaggerize

# Run specific integration spec
bundle exec rspec spec/integration/players_spec.rb

Current coverage:

• ✅ Authentication (8 endpoints)
• ✅ Players (9 endpoints)
• ✅ Matches (11 endpoints)
• ✅ Scouting (10 endpoints)
• ✅ Schedules (8 endpoints)
• ✅ Team Goals (8 endpoints)
• ✅ VOD Reviews (11 endpoints)
• ✅ Analytics (7 endpoints)
• ✅ Riot Data (14 endpoints)
• ✅ Riot Integration (1 endpoint)
• ✅ Dashboard (4 endpoints)

Total: 107 endpoints documented

Code Coverage

View coverage report after running tests:

open coverage/index.html

Deployment

Environment Variables

Required environment variables for production:

DATABASE_URL=postgresql://user:password@host:5432/database
REDIS_URL=redis://host:6379/0
JWT_SECRET_KEY=your-production-secret
RIOT_API_KEY=your-riot-api-key
CORS_ORIGINS=https://your-frontend-domain.com
SECRET_KEY_BASE=your-rails-secret

Docker

A Dockerfile is provided for containerized deployment:

docker build -t prostaff-api .
docker run -p 3333:3000 prostaff-api

CI/CD

Architecture Diagram Auto-Update

This project includes an automated workflow that keeps the architecture diagram in sync with the codebase:

• Trigger: Automatically runs when changes are made to:

  • app/modules/** - Module definitions
  • app/models/** - Data models
  • app/controllers/** - Controllers
  • config/routes.rb - Route definitions
  • Gemfile - Dependencies

• Process:

  1. GitHub Actions workflow detects relevant code changes
  2. Runs scripts/update_architecture_diagram.rb
  3. Script analyzes project structure (modules, models, controllers, services)
  4. Generates updated Mermaid diagram
  5. Updates README.md with new diagram
  6. Commits changes back to the repository

• Manual Update: You can also manually update the diagram:

  ruby scripts/update_architecture_diagram.rb

The diagram automatically reflects:

• New modules added to app/modules/
• New models created
• New controllers and routes
• Service integrations (Riot API, Redis, PostgreSQL, Sidekiq)

📊 Performance & Testing

Load Testing (k6)

# Quick smoke test (1 min)
./load_tests/run-tests.sh smoke local

# Full load test (16 min)
./load_tests/run-tests.sh load local

# Stress test (28 min)
./load_tests/run-tests.sh stress local

Current Performance:

• p(95): ~880ms (Docker dev)
• Production estimate: ~500ms
• With cache: ~50ms
• Error rate: 0%

Documentation: See TESTING_GUIDE.md and QUICK_START.md

Security Testing (OWASP)

# Complete security audit
./security_tests/scripts/full-security-audit.sh

# Individual scans
./security_tests/scripts/brakeman-scan.sh          # Code analysis
./security_tests/scripts/dependency-scan.sh        # Vulnerable gems
./security_tests/scripts/zap-baseline-scan.sh      # Web app scan

Coverage:

• ✅ OWASP Top 10
• ✅ Code security (Brakeman)
• ✅ Dependency vulnerabilities
• ✅ Runtime security (ZAP)
• ✅ CI/CD integration

Documentation: See security_tests/README.md

CI/CD Workflows

Automated testing on every push:

• Security Scan: Brakeman + dependency check
• Load Test: Nightly smoke tests
• Nightly Audit: Complete security scan

See .github/workflows/ for details.

Contributing

1. Create a feature branch
2. Make your changes
3. Add tests
4. Run security scan: ./security_tests/scripts/brakeman-scan.sh
5. Ensure all tests pass
6. Submit a pull request

Note: The architecture diagram will be automatically updated when you add new modules, models, or controllers.

License

Copyright e Licenciamento

© 2025 ProStaff.gg. Todos os direitos reservados.

Este repositório contém o código-fonte oficial da API para a plataforma de e-sports ProStaff.gg.

O código-fonte contido aqui é disponibilizado sob a licença Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License. Você pode encontrar o texto completo da licença no arquivo LICENSE neste repositório.

Shield:

This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.

Disclaimer

Prostaff.gg isn't endorsed by Riot Games and doesn't reflect the views or opinions of Riot Games or anyone officially involved in producing or managing Riot Games properties.

Riot Games, and all associated properties are trademarks or registered trademarks of Riot Games, Inc.