Django-Polymorphic - Polymorphic Item Management System

A modern Django-based item management system demonstrating polymorphic model patterns with HTMX-powered dynamic UI. Built to showcase how to handle diverse product types with shared and specialized attributes in a single, elegant architecture.

Features

• Polymorphic Models: Demonstrates Django polymorphic patterns for handling multiple product types with a single base model
• Type-Specific Forms: Dynamic forms that adapt based on item type selection
• HTMX Integration: Modern, responsive UI with server-side rendering and minimal JavaScript
• Advanced Filtering: Django-filters powered search and filtering system
• Multiple Product Types: Supports TVs, Monitors, Tablets, Laptops, Desktops, Phones, Cameras, Accessories, Components, Printers, Cars, and Food items
• Clean Architecture: Well-organized Django apps with clear separation of concerns

Technology Stack

• Framework: Django 5.0
• UI: HTMX for dynamic interactions
• Database: SQLite (development), PostgreSQL ready
• Forms: django-widget-tweaks, django-template-partials
• Filtering: django-filters
• Models: django-polymorphic for inheritance
• PDF Generation: ReportLab
• Development: django-extensions, Faker for test data

Quick Start

Prerequisites

• Python 3.11+
• pip
• virtualenv (recommended)

Installation

1. Clone the repository:

git clone <repository-url>
cd django-polymorphic

2. Create and activate virtual environment:

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

pip install -r requirements.txt

4. Set up environment variables:

cp .env.example .env
# Edit .env and set SECRET_KEY and other variables

5. Run migrations:

cd django_polymorphic
python manage.py makemigrations
python manage.py migrate

6. Seed the database with test data (optional but recommended):

python manage.py seed_database

6. Create superuser (optional):

python manage.py createsuperuser

7. Run development server:

python manage.py runserver

8. Visit http://localhost:8000 in your browser

Project Structure

django-polymorphic/
├── .env.example          # Environment variables template
├── .gitignore           # Git ignore rules
├── README.md            # This file
├── requirements.txt     # Python dependencies
├── ARCHITECTURE.md      # Architecture documentation
├── CONTRIBUTING.md      # Contribution guidelines
├── CHANGELOG.md         # Version history
└── django_polymorphic/  # Main Django project
    ├── manage.py        # Django management script
    │
    ├── django_polymorphic/ # Project configuration
    │   ├── settings.py  # Django settings
    │   ├── urls.py      # Main URL routing
    │   ├── wsgi.py      # WSGI config
    │   └── asgi.py      # ASGI config
    │
    ├── core/            # Core app (landing pages, base templates)
    │   ├── models.py    # Core models
    │   ├── views.py     # Core views
    │   ├── templates/   # Base templates
    │   └── static/      # Global static files
    │
    └── itemcomponent/   # Item management (main feature)
        ├── models.py    # Polymorphic Item models
        ├── views.py     # Item CRUD and filtering
        ├── forms.py     # Dynamic type-specific forms
        ├── filters.py   # Django-filters configuration
        ├── urls.py      # Item URLs
        ├── templates/   # Item templates with HTMX partials
        └── templatetags/ # Custom template tags

Core Apps

itemcomponent

The main item management system demonstrating polymorphic model patterns:

• Base Item Model: Common fields shared across all product types
• Specialized Models: 12+ product types (TV, Monitor, Laptop, Desktop, Tablet, Phone, Camera, Accessory, Component, Printer, Car, Food)
• Dynamic Forms: HTMX-powered forms that change based on selected item type
• Advanced Filtering: Multi-faceted search and filtering
• Type-Specific Fields: Each product type has relevant specialized attributes

core

Foundation app providing:

• Base Templates: Shared layout and navigation
• Static Files: Global CSS and JavaScript
• Landing Pages: Home page and navigation structure

Key Concepts

Polymorphic Models

This project demonstrates Django's polymorphic model inheritance pattern, allowing:

• Single database table for common attributes
• Separate tables for type-specific attributes
• Unified querying across all item types
• Type-safe attribute access

HTMX Integration

Modern UI interactions without heavy JavaScript frameworks:

• Dynamic form loading based on item type selection
• Tab-based content loading
• Partial page updates
• Server-side rendering with minimal client code

Django Best Practices

• Clean separation of concerns
• Reusable template partials
• Custom template tags
• Form validation and error handling
• Environment-based configuration

Development

Seeding Test Data

The project includes a management command to seed the database with realistic test data:

# Seed database with test data
python manage.py seed_database

# Clear existing data and reseed
python manage.py seed_database --clear

This will create sample items across all 12 product types:

• 3 TVs (Samsung, LG, Sony)
• 3 Phones (iPhone, Samsung, Google Pixel)
• 3 Laptops (MacBook Pro, Dell XPS, ThinkPad)
• 2 Desktops (Mac Studio, Dell Precision)
• 2 Monitors (Dell UltraSharp, LG UltraGear)
• 2 Tablets (iPad Pro, Galaxy Tab)
• 2 Cameras (Sony α7R V, Canon EOS R5 II)
• 2 Accessories (Logitech Mouse, Anker Power Bank)
• 2 Printers (HP LaserJet, Epson EcoTank)
• 2 Cars (Tesla Model 3, Toyota Camry)
• 2 Food items (Olive Oil, Sourdough Bread)

Running Tests

cd django_polymorphic
python manage.py test

Creating a Superuser

python manage.py createsuperuser

Admin Interface

Access Django admin at http://localhost:8000/admin/

Configuration

Environment Variables

Copy .env.example to .env and configure:

• SECRET_KEY: Django secret key (generate new one for production)
• DEBUG: Debug mode (False for production)
• ALLOWED_HOSTS: Comma-separated list of allowed hosts
• Database settings (for PostgreSQL in production)

Security Settings

For production deployment:

• Set DEBUG=False
• Generate strong SECRET_KEY
• Configure ALLOWED_HOSTS
• Enable SSL settings (SECURE_SSL_REDIRECT, etc.)
• Use PostgreSQL instead of SQLite
• Set up proper media/static file serving

URL Routes

Core

• / - Home page
• /admin/ - Django admin interface

Items

• /item/ - Item list with filtering
• /item/create/ - Create new item with dynamic type-specific form
• /item/view/<id>/ - Item detail view with tabs
• /item/view/<id>/specifications - Specifications tab content
• /item/view/<id>/detail - Detail tab content
• /item/view/<id>/documents - Documents tab content
• /item/view/<id>/videos - Videos tab content
• /item/view/<id>/bidrequest - Bid request form tab content

Models Overview

Item (Polymorphic Base)

All items share common attributes:

• long_name, short_name, model_name
• primary_type (category) and secondary_type (subcategory)
• description, blurb
• upc, weight, dimensions
• documentation_link

Specialized Item Types

Each type extends the base Item model with specific fields:

• TV: screen_size, resolution, display_type, refresh_rate, smart_platform, hdr_support, audio_features
• Monitor: screen_size, resolution, panel_type, refresh_rate, response_time, connectivity
• Tablet: screen_size, os, processor, ram, disk_space, battery_life
• Laptop: processor, ram, disk_space, screen_size, os, battery_life, connectivity
• Desktop: processor, ram, disk_space, form_factor, os
• Phone: screen_size, os, processor, ram, camera_specs, battery_capacity
• Camera: sensor_size, megapixels, lens_mount, video_resolution, iso_range
• Accessory: compatibility, connectivity, power_type
• Component: component_type, socket_compatibility, power_consumption
• Printer: print_type, print_speed, connectivity, firmware_version
• Car: make, model_year, fuel_type, transmission, engine_size
• Food: expiration_date, ingredients, allergen_info, nutritional_info

License

This project is open source and available under the MIT License.

Notes

This is a Django 5.0+ application showcasing polymorphic inheritance patterns for handling multiple product types with shared and specialized attributes. The project demonstrates how to effectively use Django's model inheritance and the django-polymorphic library to manage diverse product types in a single, unified system.