Documentation Index

Welcome to the Football Kit Archive API documentation. This index will help you find the information you need.

About This Project

The Football Kit Archive API is a Django-based REST API that provides access to a comprehensive database of football (soccer) kit information. The project scrapes and aggregates data from public sources to create a searchable, filterable API for kit enthusiasts, developers, and researchers.

Relation to FootyCollect: This API is an external service used by FootyCollect to create and manage kits, import images, and handle all related data. FootyCollect can run without it, but the API is practically essential for the full experience.

Key Features:

• RESTful API with Django Ninja
• Comprehensive kit database (clubs, seasons, brands, types)
• Advanced search and filtering capabilities
• Ethical web scraping with rate limiting
• Optional Celery integration for background tasks
• Redis caching for improved performance
• Full API documentation with Swagger UI

Disclaimer

⚠️ This is a personal learning project - This project was created for educational purposes and to practice development skills. It is not intended for commercial use or production deployment without proper review and modifications.

Important Notes:

• This project is for learning and skill development purposes
• Code quality, architecture decisions, and implementations reflect a learning journey
• Some features may be experimental or incomplete
• Always review and test thoroughly before using in any production environment
• The project respects robots.txt and implements ethical scraping practices

Table of Contents

1. About This Project
2. Disclaimer
3. Getting Started
4. Core Documentation
5. Development
6. Operations
7. Quick Reference
8. Finding Information
9. Documentation Standards
10. How to Access Documentation

---

Getting Started

• Getting Started Guide - Complete setup guide from scratch, including initial database population and ethical scraping practices
• Developer Onboarding - Guide for new developers joining the project

Core Documentation

Setup and Configuration

• Getting Started - Complete setup guide from scratch (works with or without Celery)
• Celery Setup - Optional: Guide to setting up Celery for background tasks (recommended for production)
• Architecture - System architecture and design decisions
• Data Flow - How data flows through the system
• Deployment Guide - Production deployment instructions

Scraping

• Scraping Guide - Comprehensive guide to ethical web scraping
• Quick Scraping - Quick reference for common scraping tasks

These guides cover:

• Ethical scraping practices (robots.txt, Terms of Service)
• Rate limiting and delays
• Initial data population workflow
• Daily automated scraping
• Troubleshooting

API Documentation

• Interactive API Docs - Swagger/OpenAPI interface (when server is running) ⭐
• API Endpoint Catalog - Complete list of API endpoints
• API Usage Examples - Code examples for using the API
• Postman Collection - Import this into Postman for testing

Performance and Optimization

• Caching Strategy - How caching is implemented and configured

Development

Architecture Decisions

• Decision Records - Architecture Decision Records (ADRs)
  • 0001: Scraping Framework
  • 0002: Tooling and Standards

Operations

• Troubleshooting - Common issues and solutions

Quick Reference

Starting Services

Windows:

# Celery Worker
fkapi\start_celery_worker.bat

# Celery Beat
fkapi\start_celery_beat.bat

Linux/Mac:

# Celery Worker
./fkapi/start_celery_worker.sh

# Celery Beat
./fkapi/start_celery_beat.sh

Common Commands

# Run migrations
python manage.py migrate

# Create superuser
python manage.py createsuperuser

# Scrape latest kits
python manage.py scrape_latest --start-page 1 --end-page 5

# Scrape a club
python manage.py scrape_whole_club --club-slug "arsenal-kits"

# Run tests
pytest

# Lint code
ruff check .
ruff format .

Finding Information

I want to...

• Set up the project from scratch → Getting Started Guide
• Set up without Celery → Getting Started Guide (works without Celery)
• Configure Celery (optional) → Celery Setup (recommended for production)
• Learn about ethical scraping → Scraping Guide
• Quick scraping reference → Quick Scraping
• Deploy to production → Deployment Guide
• Understand the architecture → Architecture
• Use the API → API Endpoint Catalog
• Troubleshoot issues → Troubleshooting
• Understand decisions → Decision Records
• Onboard as developer → Developer Onboarding

Documentation Standards

All documentation should:

• Be written in English
• Use clear, concise language
• Include code examples where relevant
• Be kept up to date with code changes
• Follow markdown best practices

How to Access Documentation

API Documentation (Interactive) ⭐ PRIMARY

Django Ninja automatically generates an interactive API documentation interface.

1. Start the Django server:

   cd fkapi
   python manage.py runserver

2. Open your browser:

   http://localhost:8000/api/docs
   

Features:

• Interactive Swagger UI
• Test endpoints directly from browser
• View request/response schemas
• See authentication requirements
• Download OpenAPI schema

Project Documentation (Markdown)

Access Methods:

1. Direct File Access: Open .md files in your IDE or text editor
2. GitHub Web Interface: View formatted documentation when pushed to repository
3. Local Server: Use python -m http.server or MkDocs (see Documentation Access Guide)

For detailed information, see: Documentation Access Guide

External Resources

• Django Documentation: https://docs.djangoproject.com/
• Celery Documentation: https://docs.celeryq.dev/
• Redis Documentation: https://redis.io/docs/

---

Last Updated: 2026-01-17 Maintained by: sunr4y