Skip to main content
FootyCollect follows a modular Django project structure with clear separation of concerns. This guide explains the organization and purpose of each major directory.

​
Directory Overview

footycollect/
├── config/              # Django settings and configuration
│   ├── settings/        # Environment-specific settings
│   ├── celery_app.py   # Celery configuration
│   └── checks.py        # Production validation checks
├── footycollect/       # Main application code
│   ├── api/             # API client for external services (FKAPI)
│   ├── collection/     # Collection app (items, photos, etc.)
│   ├── core/            # Core models (clubs, seasons, etc.)
│   ├── users/           # User management
│   ├── static/          # Static assets (CSS, JS, images)
│   └── templates/       # Django templates
├── deploy/              # Production deployment files
├── docs/                # Architecture and Sphinx documentation
├── compose/             # Docker Compose service definitions
├── requirements/        # Python dependencies
├── tests/               # Project-wide test fixtures
├── locale/              # Internationalization files
└── media/               # User-uploaded media files

​
Key Directories

​
config/

Contains Django project settings and configuration.
Environment-specific settings modules:
  • base.py - Shared settings for all environments
  • local.py - Development settings
  • production.py - Production settings
  • test.py - Test environment settings
Celery application initialization and configuration. Autodiscovers tasks from all registered Django apps.
Production readiness validation checks. Run with python manage.py check --deploy.

​
footycollect/

The main application package containing all Django apps.

​
footycollect/collection/

The core collection app managing items and photos: 
collection/
├── models.py            # BaseItem, Jersey, Shorts, Photo models
├── views/               # View classes and mixins
│   └── jersey/          # Jersey-specific views
├── services/            # Business logic layer
├── repositories/        # Data access layer
├── management/          # Django management commands
│   └── commands/
├── templatetags/        # Custom template tags
└── tests/               # Test suite
The collection app follows a service layer pattern - business logic lives in services/, not in views or models. See the Service Layer documentation.

​
footycollect/api/

External API integration (FKAPI client) for the Football Kit Archive:
  • API client implementation
  • Request/response handling
  • Integration with collection services

​
footycollect/core/

Shared core models and utilities:
  • Club, Season, Competition models
  • Shared utilities and helpers
  • Common base classes

​
footycollect/users/

User management and authentication:
  • User model
  • Profile management
  • Authentication views

​
deploy/

Production deployment configuration:
  • env.example - Environment variable template
  • Deployment scripts and configurations
  • Server setup documentation
See the Deployment Guide for details.

​
compose/

Docker Compose service definitions: 
Development services:
- Django
- PostgreSQL
- Redis
- Celery worker
- Celery beat
- Mailpit (email testing)

​
Test Organization

Tests are organized by app within each app’s tests/ directory: 
footycollect/collection/tests/
├── test_models.py           # Model tests
├── test_views/              # View tests (organized by view type)
├── test_services.py         # Service layer tests
├── test_forms.py            # Form validation tests
├── test_repositories.py     # Repository layer tests
├── test_tasks.py            # Celery task tests
└── test_e2e_*.py           # End-to-end tests
All tests run from the project root with pytest. Configuration is in pytest.ini and pyproject.toml.

​
Multi-Table Inheritance Structure

FootyCollect uses Django’s Multi-Table Inheritance (MTI) for item types: 
BaseItem (base class)
├── Jersey (specific item type)
├── Shorts (specific item type)
├── Outerwear (specific item type)
└── Tracksuit (specific item type)
Each item type:
  • Inherits common fields from BaseItem
  • Has a one-to-one relationship with BaseItem
  • Adds type-specific fields and behavior
See Multi-Table Inheritance ADR for the design rationale.

​
Finding Your Way Around

1

Models

Look in footycollect/<app>/models.py for data models
2

Business Logic

Check footycollect/<app>/services/ for business logic (not in views!)
3

Views

Find view classes in footycollect/<app>/views/
4

Forms

Forms are in footycollect/<app>/forms.py
5

Templates

Templates are in footycollect/templates/<app>/
6

Background Tasks

Celery tasks are in footycollect/<app>/tasks.py

​
Next Steps

Running Tests

Learn how to run the test suite

Code Quality

Code quality tools and standards

Celery Tasks

Background task processing

Architecture

Learn about the architecture

Build docs developers (and LLMs) love

Get started for freeTalk to us