Architecture Overview

​

Technology Stack

• Framework: Django 5.0+ - Python web framework with ORM, admin interface, and authentication
• Database: PostgreSQL - Primary relational database with support for complex queries and indexes
• Cache & Broker: Redis - Used for caching and as Celery message broker
• Task Queue: Celery - Asynchronous task processing for background jobs (image processing, etc.)
• API: Django REST Framework - RESTful API for programmatic access
• Image Processing: Pillow + ImageKit - Image optimization and format conversion (AVIF)
• Frontend: Django Templates with Bootstrap 5 and django-cotton components

​

Architecture Layers

┌─────────────────────────────────────────┐
│  Views Layer (HTTP/Templates)           │
│  - Django views & viewsets              │
│  - REST API endpoints                   │
└─────────────┬───────────────────────────┘
              │
┌─────────────▼───────────────────────────┐
│  Service Layer (Business Logic)         │
│  - ItemService, PhotoService, etc.      │
│  - Transaction management               │
│  - External API integration             │
└─────────────┬───────────────────────────┘
              │
┌─────────────▼───────────────────────────┐
│  Repository Layer (Data Access)         │
│  - ItemRepository, PhotoRepository      │
│  - Query optimization                   │
└─────────────┬───────────────────────────┘
              │
┌─────────────▼───────────────────────────┐
│  Models Layer (ORM/Database)            │
│  - BaseItem, Jersey, Shorts, etc.       │
│  - Multi-table inheritance              │
└─────────────────────────────────────────┘

​

Layer Responsibilities

• Handle HTTP requests and responses
• Render templates or serialize JSON
• Request validation and form handling
• Minimal business logic

• Encapsulate complex business logic
• Coordinate multiple repositories
• Manage database transactions
• Integrate with external APIs
• Orchestrate async tasks

• Abstract database access patterns
• Encapsulate complex queries
• Provide a clean data access API
• Handle query optimization

• Define database schema via Django ORM
• Implement data validation
• Define model-level business rules
• Manage relationships

​

Key Design Patterns

​

Multi-Table Inheritance (MTI)

BaseItem (common fields)
├── Jersey (jersey-specific fields)
├── Shorts (shorts-specific fields)
├── Outerwear (outerwear-specific fields)
└── Tracksuit (tracksuit-specific fields)

• Clear separation of common and type-specific fields
• Type safety with distinct models
• Flexibility to query all items or specific types
• Easy extensibility for new item types

​

Service Layer Pattern

from footycollect.collection.services import get_item_service

item_service = get_item_service()
item = item_service.create_item_with_photos(user, item_data, photos)

• Reusable business logic across views, APIs, and tasks
• Easier unit testing without HTTP layer
• Clear transaction boundaries
• Better separation of concerns

​

Repository Pattern

class ItemRepository:
    def get_user_items(self, user):
        return BaseItem.objects.filter(user=user)
    
    def get_public_items(self):
        return BaseItem.objects.filter(is_private=False, is_draft=False)

• Centralized query logic
• Easier to optimize queries
• Testable data access layer
• Flexibility to change data source

​

Service Registry Pattern

class ServiceRegistry:
    def get_item_service(self) -> ItemService:
        return self.get_service('item_service')

# Global registry
service_registry = ServiceRegistry()
service_registry.initialize_default_services()

​

Data Flow Example

1. User creates a jersey via web form
2. View validates form and extracts data
3. Service (ItemService) coordinates the operation:
   • Starts database transaction
   • Creates BaseItem record
   • Creates Jersey record (linked to BaseItem)
   • Processes photo uploads via PhotoService
   • Commits transaction
4. Repository executes optimized database queries
5. Models enforce data validation and relationships
6. View redirects to item detail page

​

Database Design

• Multi-table inheritance for item types
• Foreign keys for relationships (user, club, season, brand)
• Many-to-many for competitions and colors
• Generic foreign keys for flexible photo associations
• Indexes on common query patterns (user+type, club+season)

​

External Integrations

​

Football Kit Archive API

• Fetch kit metadata (team, season, type)
• Download official kit images
• Populate collection data automatically

class ItemFKAPIService:
    def process_item_creation(self, form, user, item_type):
        # Fetch data from FKAPI
        # Create item with enriched metadata
        # Download and attach photos

​

Asynchronous Processing

• Image optimization: Convert uploaded images to AVIF format
• Photo processing: Resize and generate thumbnails
• External API calls: Fetch data without blocking requests

@shared_task
def process_photo_to_avif(photo_id):
    photo = Photo.objects.get(pk=photo_id)
    photo.create_avif_version()

​

Security & Performance

​

Security Measures

• Authentication: Django Allauth with email verification
• Authorization: User-based ownership checks
• Content Security Policy: Configurable CSP headers
• Input validation: Form validation and model constraints
• File upload validation: Type and size limits for images

​

Performance Optimizations

• Database indexes: Composite indexes on common query patterns
• Query optimization: select_related() and prefetch_related()
• Caching: Redis for session storage and caching
• Image optimization: AVIF format for smaller file sizes
• Asynchronous processing: Celery for heavy operations

​

Related Documentation