# jdiazromeral/django-ddd architecture

> Architecture diagram of the GitHub repository jdiazromeral/django-ddd, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jdiazromeral/django-ddd
- Repository: https://github.com/jdiazromeral/django-ddd

## Overview

##### Project Type and Purpose
- This is an **open-source tool/library** that plugs into Django.
- It provides a **management command** (`start_clean_app`) and an **app‐config helper** (`CleanAppConfig`) to scaffold and configure Django apps in a Domain-Driven Design (DDD) style.

##### File Structure
- Top-level “django_ddd/” package contains:
- `_app_template/` – a directory of template files (application/, domain/, infrastructure/) used by the generator.
- `apps_config/` – logic to customize Django’s app registry (CleanAppConfig).
- `management/commands/start_clean_app.py` – the CLI entry point.
- A dummy_app/ folder and tests/ exist for validation.
- Support files: setup.py, Pipfile, Dockerfile, GitHub Actions workflows.

a. Developer CLI Layer
- **manage.py** invokes Django’s management framework.
- `start_clean_app` command is registered under `django_ddd.management.commands`.
b. Generator Core
- The command loads template files from `django_ddd/_app_template`.
- It renders and writes out a new app folder with subdirectories: application/, domain/, infrastructure/.
c. App‐Config Integration
- `CleanAppConfig` (in `apps_config/clean_app_config.py`) extends Django’s AppConfig.
- It adjusts `models`, `migrations`, `admin` module lookups using user-provided settings (`CUSTOM_MODELS_MODULE`, etc.).
d. Generated App Structure
- New apps are wired into Django by adding `"app_name.infrastructure.apps.AppNameConfig"` to INSTALLED_APPS.
- At runtime, Django uses CleanAppConfig to locate infrastructure.models, infrastructure.migrations, infrastructure.admin.
e. Test & CI Pipeline
- Unit tests in tests/ exercise both the command and config.
- Dockerfile + GitHub Actions handle build, test, and publish flows.

##### Relationships and Interactions
- **Developer → CLI**: shell → `python manage.py start_clean_app` →
→ **Generator Core** (loads templates) → writes → **File System** (new app).
- **Runtime**: Django AppRegistry loads CleanAppConfig →
→ redirects model/admin/migration imports to infrastructure submodules →
→ Django ORM & admin use those.
- **CI/CD**: pushes to GitHub → triggers workflows (django.yml, pythonpublish.yml) →
→ builds Docker image → runs tests → publishes package.

##### Architectural Patterns & Design Principles
- **Template Method**: file scaffolding uses a static directory of templates.
- **Extension Point**: CleanAppConfig dynamically alters Django’s discovery of app modules.
- **Separation of Concerns**:
- _app_template (pure templates)
- management.commands (CLI logic)
- apps_config (Django integration)
- tests (quality assurance)
- **Domain-Driven Structure**: every generated app has distinct `domain/`, `application/`, and `infrastructure/`.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Pre-Generate Phase
    subgraph "Pre-Generate Phase"
        Developer(("Developer")):::actor
        CLI["manage.py"]:::cli
        Cmd["start_clean_app (Command Handler)"]:::cli
        TInit["Template __init__.py"]:::template
        TApp["Application templates"]:::template
        TDomain["Domain templates"]:::template
        TInfraTemplate["Infrastructure templates"]:::template
        FS["Filesystem Output\n(dummy_app/)"]:::generated

        Developer -->|"runs"| CLI
        CLI -->|"invokes"| Cmd
        Cmd -->|"reads"| TInit
        Cmd -->|"reads"| TApp
        Cmd -->|"reads"| TDomain
        Cmd -->|"reads"| TInfraTemplate
        Cmd -->|"writes"| FS
    end

    %% Generated App Structure
    subgraph "Generated App Structure"
        DummyApp["dummy_app/"]:::generated
        AppDir["application/"]:::generated
        DomainDir["domain/"]:::generated
        Infra["infrastructure/"]:::generated
        InfraAdmin["admin.py"]:::generated
        InfraApps["apps.py"]:::generated
        InfraMigs["migrations/"]:::generated
        InfraModels["models.py"]:::generated

        FS --> DummyApp
        DummyApp --> AppDir
        DummyApp --> DomainDir
        DummyApp --> Infra
        Infra --> InfraAdmin
        Infra --> InfraApps
        Infra --> InfraMigs
        Infra --> InfraModels
    end

    %% Runtime Phase
    subgraph "Runtime Phase"
        AppRegistry["Django AppRegistry"]:::runtime
        CleanConfig["CleanAppConfig"]:::config
        ORM["Django ORM & Admin"]:::runtime

        AppRegistry -->|"loads"| CleanConfig
        CleanConfig -->|"redirects imports to infrastructure submodules"| ORM
    end

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        GHActions["GitHub Actions Workflows"]:::ci
        Docker["Dockerfile"]:::ci
        TestsCmd["test_start_clean_app.py"]:::ci
        TestsConfig["test_clean_app_config.py"]:::ci

        GHActions -->|"builds image"| Docker
        GHActions -->|"runs tests"| TestsCmd
        GHActions -->|"runs tests"| TestsConfig
    end

    %% Cross-Phase Connections
    FS -->|"later discovered by"| AppRegistry
    Developer -.->|"pushes code"| GHActions

    %% Click Events
    click CLI "https://github.com/jdiazromeral/django-ddd/blob/master//manage.py"
    click Cmd "https://github.com/jdiazromeral/django-ddd/blob/master//django_ddd/management/commands/start_clean_app.py"
    click TInit "https://github.com/jdiazromeral/django-ddd/blob/master//django_ddd/_app_template/__init__.py"
    click TApp "https://github.com/jdiazromeral/django-ddd/tree/master//django_ddd/_app_template/application/"
    click TDomain "https://github.com/jdiazromeral/django-ddd/tree/master//django_ddd/_app_template/domain/"
    click TInfraTemplate "https://github.com/jdiazromeral/django-ddd/tree/master//django_ddd/_app_template/infrastructure/"
    click CleanConfig "https://github.com/jdiazromeral/django-ddd/blob/master//django_ddd/apps_config/clean_app_config.py"
    click GHActions "https://github.com/jdiazromeral/django-ddd/blob/master//.github/workflows/django.yml"
    click Docker "https://github.com/jdiazromeral/django-ddd/tree/master//Dockerfile"
    click TestsCmd "https://github.com/jdiazromeral/django-ddd/blob/master//tests/django_ddd/management/commands/test_start_clean_app.py"
    click TestsConfig "https://github.com/jdiazromeral/django-ddd/blob/master//tests/django_ddd/apps_config/test_clean_app_config.py"

    %% Styles
    classDef actor fill:#D0E6FF,stroke:#339,stroke-width:1px;
    classDef cli fill:#CFE2F3,stroke:#2A6F97,stroke-width:1px;
    classDef template fill:#E2F0D9,stroke:#629F4A,stroke-width:1px;
    classDef generated fill:#D9EAD3,stroke:#6AA84F,stroke-width:1px;
    classDef config fill:#FFF2CC,stroke:#BF9000,stroke-width:1px;
    classDef runtime fill:#FCE5CD,stroke:#E69138,stroke-width:1px;
    classDef ci fill:#EEEEEE,stroke:#999999,stroke-width:1px;
```
