Skip to main content

​
Architecture Overview

Django SuperApp is a modular framework that extends Django to enable rapid project development through pre-built, standalone apps. The framework provides an automatic discovery and integration system that makes Django projects more organized and scalable.

​
Core Architecture

Django SuperApp enhances the standard Django project structure by introducing an automated app discovery and integration mechanism. Instead of manually configuring each app in your project’s settings and URLs, SuperApp automatically detects and integrates apps placed in the superapp/apps/ directory.

​
How SuperApp Extends Django

The framework provides two core integration points:
  1. Settings Integration - Automatically discovers and executes extend_superapp_settings() functions from each app’s settings.py
  2. URL Integration - Automatically discovers and executes URL extension functions from each app’s urls.py
This architecture allows each app to be truly self-contained with its own configuration, routes, and dependencies.

​
App Discovery Mechanism

SuperApp uses Python’s pkgutil.iter_modules() to automatically discover all apps within the superapp/apps/ directory. The discovery process:
  1. Iterates through all modules in the apps package
  2. Attempts to import settings.py and urls.py from each app
  3. Executes integration functions if they exist
  4. Gracefully continues if an app doesn’t have these files

​
Settings Discovery

From src/django_superapp/settings.py:9-21: 
def extend_superapp_settings(main_settings, superapp_apps):
    for importer, modname, ispkg in pkgutil.iter_modules(superapp_apps.__path__):
        submodule_name = f"{superapp_apps.__name__}.{modname}.settings"

        try:
            settings_module = importlib.import_module(submodule_name)
        except ModuleNotFoundError as e:
            if f"No module named '{submodule_name}'" in str(e):
                continue
            raise e

        if hasattr(settings_module, "extend_superapp_settings"):
            settings_module.extend_superapp_settings(main_settings)
This function:
  • Dynamically imports each app’s settings module
  • Checks if extend_superapp_settings() exists
  • Passes the main settings dictionary for modification
  • Handles missing modules gracefully

​
URL Discovery

From src/django_superapp/urls.py:7-19: 
def extend_superapp_urlpatterns(main_urlpatterns, package):
    for importer, modname, ispkg in pkgutil.iter_modules(package.__path__):
        submodule_name = f"{package.__name__}.{modname}.urls"

        try:
            urls_module = importlib.import_module(submodule_name)
        except ModuleNotFoundError as e:
            if f"No module named '{submodule_name}'" in str(e):
                continue
            raise e

        if hasattr(urls_module, "extend_superapp_urlpatterns"):
            urls_module.extend_superapp_urlpatterns(main_urlpatterns)
Similar to settings discovery, this function automatically integrates URL patterns from each app.

​
Project Structure Conventions

Django SuperApp follows a standardized project structure: 
my_superapp/
├── superapp/
│   ├── apps/
│   │   ├── admin_portal/
│   │   │   ├── settings.py          # App-specific settings
│   │   │   ├── urls.py              # App-specific URLs
│   │   │   ├── requirements.txt     # App-specific dependencies
│   │   │   ├── models.py
│   │   │   ├── views.py
│   │   │   └── admin/
│   │   │       └── *.py             # Admin configurations
│   │   ├── authentication/
│   │   │   ├── settings.py
│   │   │   ├── urls.py
│   │   │   ├── requirements.txt
│   │   │   └── ...
│   │   └── your_app/
│   │       ├── settings.py          # Required for settings integration
│   │       ├── urls.py              # Required for URL integration
│   │       ├── requirements.txt     # Optional app dependencies
│   │       └── ...
│   ├── settings.py                  # Main project settings
│   └── urls.py                      # Main project URLs
├── manage.py
└── requirements.txt                 # Project-wide dependencies

​
Key Conventions

All SuperApp apps must be placed in superapp/apps/ directory for automatic discovery.
Each app should have a settings.py with an extend_superapp_settings(main_settings) function to configure the app.
Each app should have a urls.py with extend_superapp_urlpatterns(main_urlpatterns) function to register routes.
Each app can have its own requirements.txt for app-specific Python packages.
Admin configurations must live in superapp/apps/<app_name>/admin/<model_name_slug>.py for proper organization.

​
Benefits of SuperApp Architecture

Modularity

Each app is completely self-contained with its own settings, URLs, and dependencies.

Reusability

Apps can be easily shared across projects or published as templates.

Automatic Integration

No manual configuration needed - just drop an app in the apps directory.

Scalability

Add or remove apps without modifying core project files.

​
Integration Flow

When your Django SuperApp project starts:
The discovery mechanism is fault-tolerant - if an app doesn’t have settings.py or urls.py, it’s simply skipped without errors.

​
Next Steps

App System

Learn how to structure and create SuperApp apps

Settings Integration

Deep dive into app settings integration

URL Integration

Understand URL pattern integration

Build docs developers (and LLMs) love

Get started for freeTalk to us