Case Study 01: Modernizing a 10-Year-Old Django Application

Background

TechMart is an online electronics retailer whose e-commerce platform was originally built in 2014 using Django 1.6 and Python 2.7. Over the past decade, the application has grown organically under the hands of more than twenty developers, none of whom still work at the company. The application serves approximately 50,000 daily active users and processes around 2,000 orders per day.

The codebase consists of 95,000 lines of Python spread across 340 files. It has 8% test coverage, primarily concentrated around a few utility functions written by a testing-conscious developer who left in 2017. The application runs on a single Django monolith with a PostgreSQL database, served by Gunicorn behind Nginx.

The Problems

The decision to modernize was driven by several converging pressures:

Security vulnerabilities. Django 1.6 reached end-of-life in 2015, and the application has accumulated at least a dozen known CVEs in its framework and dependencies. The security team has flagged this as a critical risk for the past three quarterly reviews.

Python 2.7 end-of-life. Python 2.7 lost official support in January 2020. Libraries that TechMart depends on have dropped Python 2 support, freezing their versions and preventing access to bug fixes and security patches.

Developer productivity. New developers take an average of six weeks to become productive because the codebase has no documentation, inconsistent patterns, and numerous implicit conventions that can only be learned through trial and error. Two promising candidates declined job offers after reviewing the codebase during technical interviews.

Feature velocity. Simple feature requests that should take days routinely take weeks because of tangled dependencies, lack of tests (requiring extensive manual QA), and fear of unintended side effects.

Scalability limitations. The synchronous Django monolith struggles during flash sales, and the team has been unable to implement real-time features that competitors offer because of the outdated architecture.

The Modernization Strategy

The team decided on a six-phase, 40-week incremental modernization strategy. They explicitly rejected a "Big Bang" rewrite after studying industry case studies showing that multi-year rewrites of business-critical applications fail more often than they succeed.

Phase 1: Assessment and Safety Net (Weeks 1-6)

AI-Assisted Codebase Analysis. The team used an AI coding assistant to perform a rapid analysis of the entire codebase. They fed the assistant key files — settings.py, the URL configuration, the most-imported modules, and the largest files — and asked it to map the architecture.

The AI identified: - 14 Django apps, 5 of which were essentially unused but still imported - A "God model" (Order) with 47 fields and 32 methods - Circular dependencies between orders, inventory, and payments apps - Raw SQL queries in 23 different files, some with SQL injection vulnerabilities - 8 different patterns for handling authentication (decorators, mixins, middleware, manual checks) - A custom template tag library with 140 tags, many of which duplicated Django built-in functionality

Characterization Tests. The team focused characterization testing on the three most critical paths: order placement, payment processing, and inventory management. They used AI to generate test cases:

Prompt: "Here is the order placement flow across three Django
views and two model methods. Generate characterization tests
that capture the current behavior for: successful orders,
orders with out-of-stock items, orders with invalid payment
methods, orders with coupon codes, and orders exceeding the
maximum quantity limit."

The AI generated 67 characterization tests, of which 61 passed immediately. The six failures revealed unexpected behaviors that the team documented. After manual additions, they had 89 characterization tests covering the critical paths, achieving 34% coverage of the code they planned to modify.

CI/CD Pipeline. The team set up GitHub Actions for continuous integration, running the characterization tests on every pull request. They also added flake8 for basic linting and safety for dependency vulnerability scanning.

Phase 2: Python 3 Migration (Weeks 7-14)

The Python 2 to 3 migration was the highest-priority structural change because it unblocked all other modernization work.

Automated Conversion. The team used the 2to3 tool for the initial conversion, then used AI to handle the cases that 2to3 could not resolve:

Prompt: "This code uses Python 2 dictionary methods (.has_key,
.iteritems, .itervalues) and print statements. Convert it to
Python 3, also fixing any unicode/bytes issues you see. The
application deals with product names that may contain
international characters."

Dual Compatibility Period. For two weeks, the team ran the application under both Python 2.7 and Python 3.8 in their CI pipeline, using the six compatibility library where needed. This caught several subtle incompatibilities, particularly around string encoding in the payment processing module.

Database Driver Update. The migration from psycopg2 (Python 2 version) to psycopg2-binary required updating connection string handling in several places. AI helped identify all the locations:

Prompt: "Find every place in this codebase where a database
connection is created or configured. Include both the Django
settings and any direct psycopg2 usage."

Phase 3: Django Upgrade Path (Weeks 15-22)

Upgrading from Django 1.6 to Django 4.2 required stepping through several intermediate versions because of breaking changes at each major version boundary.

Upgrade Steps: 1. Django 1.6 to 1.11 (the last 1.x release) 2. Django 1.11 to 2.2 (introducing URL path syntax changes) 3. Django 2.2 to 3.2 (middleware changes, ASGI support) 4. Django 3.2 to 4.2 (current LTS release)

At each step, the team: - Used AI to identify the specific breaking changes relevant to their codebase - Ran characterization tests to catch regressions - Fixed deprecation warnings before proceeding to the next version - Updated third-party packages that required specific Django versions

The most challenging upgrade was 1.11 to 2.2, which required: - Converting all url() calls to path() or re_path() - Updating middleware to the new-style MIDDLEWARE setting - Replacing django.core.urlresolvers imports with django.urls - Updating on_delete for all ForeignKey fields (now required)

AI assistance was particularly valuable here. The team fed the deprecation warnings into the AI and asked for fixes:

Prompt: "Here are 45 deprecation warnings from Django 2.0.
For each warning, show me the exact code change needed. Group
them by type of change."

Phase 4: Structural Refactoring (Weeks 23-30)

With the application running on modern Django and Python, the team tackled structural issues.

Breaking Up the God Model. The 47-field Order model was split into four related models: - Order — core order information (customer, status, timestamps) - OrderLineItem — individual products in the order - OrderPayment — payment method and transaction details - OrderShipment — shipping address, tracking, delivery status

AI helped design the migration:

Prompt: "I need to split this Django model into four related
models. Design the new models, the database migration strategy
(that avoids downtime), and a backward-compatible API so
existing code continues to work during the transition."

The key challenge was maintaining backward compatibility during the migration. The team used Django model properties to provide the old interface while the underlying data moved to the new structure:

class Order(models.Model):
    # New: core fields only
    customer = models.ForeignKey(Customer, on_delete=models.PROTECT)
    status = models.CharField(max_length=20)
    created_at = models.DateTimeField(auto_now_add=True)

    @property
    def shipping_address(self):
        """Backward compatibility: delegates to OrderShipment."""
        shipment = self.shipments.first()
        return shipment.address if shipment else None

Eliminating Circular Dependencies. The circular dependency between orders, inventory, and payments was resolved by introducing a services layer that coordinated between the three domains:

orders <-> inventory <-> payments  (BEFORE: circular)

orders -> services <- payments     (AFTER: services mediates)
              |
          inventory

Consolidating Authentication. The eight different authentication patterns were replaced with a single Django middleware and a set of permission decorators, following Django's built-in authentication framework.

Phase 5: Performance and Scalability (Weeks 31-36)

Query Optimization. AI analyzed the 23 files containing raw SQL and identified optimization opportunities:

Prompt: "Analyze these raw SQL queries and for each one:
1. Can it be replaced with a Django ORM query?
2. Does it have the N+1 query problem?
3. Are there missing indexes that would improve performance?
4. Is it vulnerable to SQL injection?"

The team replaced 19 of 23 raw SQL usages with ORM queries, keeping 4 complex reporting queries as raw SQL but parameterizing them properly to eliminate injection risks.

Caching Layer. The team introduced Django's caching framework with Redis, focusing on the product catalog pages that received the most traffic. AI helped identify cacheable views:

Prompt: "Which of these view functions return data that
changes infrequently and could benefit from caching? For each
one, suggest an appropriate cache timeout."

Async Views. With Django 4.2's ASGI support, the team converted the most I/O-bound views to async, particularly the payment processing flow that made multiple external API calls.

Phase 6: Cleanup and Documentation (Weeks 37-40)

Type Hints. AI added type hints to the 50 most-imported functions and all public class interfaces, catching several type-related bugs in the process.

Documentation. The team used AI to generate architectural documentation, API documentation, and onboarding guides based on the now-clean codebase.

Removing Dead Code. The 5 unused Django apps and 67 unreferenced template tags were removed after AI confirmed they were truly unused:

Prompt: "Verify that the following Django apps are not
referenced anywhere in the codebase: legacy_reports,
old_checkout, admin_v1, beta_features, import_tools.
Check URLs, settings, imports, templates, and management
commands."

Results

After 40 weeks of incremental modernization, alongside continued feature development:

Key Lessons

1. The Python 2 to 3 migration was the hardest part — not because of syntax differences, but because of subtle encoding issues in data that had been stored in the database over a decade. The team spent an entire week resolving encoding issues in customer names and addresses.

2. Characterization tests were essential. Without them, the team would not have had the confidence to make the Django upgrade jumps. Several characterization tests caught regressions that would have reached production.

3. AI saved weeks of analysis time. Tasks that would have required a developer to read thousands of lines of code — mapping dependencies, finding all usages of a pattern, identifying dead code — were completed in minutes with AI assistance.

4. Incremental improvement maintained team morale. Because the team could see measurable progress each week and continued delivering features, there was never a point where the modernization felt like a hopeless slog.

5. The hardest decisions were about what NOT to refactor. Several areas of the codebase were ugly but stable. The team had to resist the urge to "fix everything" and stay focused on changes that delivered measurable value.

6. Backward compatibility layers were essential. Properties, wrapper functions, and deprecation warnings allowed the team to change internal implementations without breaking the rest of the codebase. These layers were removed only after all consumers had been updated.