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