# thatdipen/django-sample architecture

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

- Interactive diagram: https://gitdiagram.com/thatdipen/django-sample
- Repository: https://github.com/thatdipen/django-sample

## Overview

##### Project Type and Purpose
- Full-stack web application built with Django, following Domain-Driven Design (DDD) principles.
- Provides user signup/login flows, email verification (SendGrid), asynchronous tasks (Celery), custom logging, and exception handling.

##### File Structure
- Layered (“hexagonal”) architecture under the `core/` package:
- core/domain → Entities, value objects, domain services, migrations
- core/application → Use-case–level services
- core/infrastructure → Implementations of external services (mail, logging)
- core/interface → HTTP adapters: Django views, URLs, background tasks
- core/driver → Entry points: ASGI/WSGI bootstrappers, Celery app
- Top-level: `templates/` & `core/static/` for UI, `manage.py` and `settings.py` for configuration, `requirements.txt` for dependencies, `utils/` for shared utilities.

##### README for Insights
- Key components: Django web server, PostgreSQL (or another RDBMS), Celery worker, message broker (Redis/RabbitMQ), SendGrid API, custom logging service.
- Architectural principles: loosely coupled modules, data classes, reusability.

##### Main Components and Their Interactions
a. User’s Browser (Frontend)
- Requests HTML pages & static JS → Served by Django’s static handlers and template engine.
b. Web Layer (Django Server)
- Entry via core/driver ASGI/WSGI → URL routing in core/interface/urls.py → views in core/interface/users/views.py
c. Application Layer
- Views delegate to application services (`core/application/users/services.py`) which orchestrate domain logic.
d. Domain Layer
- Business rules in `core/domain/users/models.py` and domain services (`core/domain/users/services.py`).
e. Infrastructure Layer
- Email service: `core/infrastructure/mailing_services/services.py` (SendGrid)
- Logging service: `core/infrastructure/log_services/services.py`
f. Async Task Layer
- Celery configured in core/celery.py → tasks in `core/interface/users/tasks.py` → execute application/domain logic asynchronously.
g. Database
- Django ORM mapping to the RDBMS via models and migrations.
h. External Services
- Message broker (Redis/RabbitMQ) for Celery
- SendGrid API for mail delivery
- Optional: third-party auth, monitoring, etc.

##### Architectural Patterns and Principles
- Layered/hexagonal (ports & adapters) architecture: each layer only depends on inner layers via interfaces.
- DDD: Separation of domain entities, services, and application use cases.
- Asynchronous processing with Celery for long-running tasks (e.g., sending emails, password resets).
- Utility modules (`utils/`) provide shared functionality (type conversion, custom exceptions).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        Browser["User's Browser"]:::frontend
        Templates["HTML Templates\n(templates/)"]:::frontend
        StaticAssets["Static JS Utilities\n(core/static/js/utils.js)"]:::frontend
    end

    Browser -->|"loads"| Templates
    Browser -->|"loads"| StaticAssets
    Browser -->|"HTTP"| ASGI
    Browser -->|"HTTP"| WSGI

    %% Web/API Layer
    subgraph "Web/API Layer"
        direction TB
        ASGI["Django ASGI Bootstrapper"]:::webapi
        WSGI["Django WSGI Bootstrapper"]:::webapi
        GlobalURLs["Global URL Routing\n(core/interface/urls.py)"]:::webapi
        UserURLs["User URL Routing\n(core/interface/users/urls.py)"]:::webapi
        Views["User HTTP Views\n(core/interface/users/views.py)"]:::webapi
    end

    ASGI --> GlobalURLs
    WSGI --> GlobalURLs
    GlobalURLs --> UserURLs
    UserURLs --> Views

    %% Async Task Layer
    subgraph "Async Task Layer"
        direction TB
        CeleryApp["Celery App Configuration\n(core/celery.py)"]:::webapi
        Broker["Message Broker\n(Redis/RabbitMQ)"]:::external
        Tasks["User Tasks\n(core/interface/users/tasks.py)"]:::webapi
    end

    Views -->|"enqueue AMQP"| Broker
    CeleryApp --> Broker
    Broker --> Tasks
    Tasks --> AppService

    %% Application Layer
    subgraph "Application Layer"
        direction TB
        AppService["UserService\n(core/application/users/services.py)"]:::app
    end

    Views --> AppService

    %% Domain Layer
    subgraph "Domain Layer"
        direction TB
        DomainService["User Domain Services\n(core/domain/users/services.py)"]:::domain
        UserModel["User Model (ORM)\n(core/domain/users/models.py)"]:::domain
        Migrations["Migrations\n(core/domain/users/migrations/)"]:::domain
        TextChoices["Shared Enums\n(core/domain/text_choices.py)"]:::domain
    end

    AppService --> DomainService
    Tasks --> DomainService
    DomainService --> UserModel
    UserModel --> DB
    Migrations --> DB
    TextChoices --> DomainService

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        direction TB
        MailService["Mailing Service\n(core/infrastructure/mailing_services/services.py)"]:::infra
        LogService["Logging Service\n(core/infrastructure/log_services/services.py)"]:::infra
    end

    Tasks --> MailService
    MailService --> SendGrid
    Views --> LogService
    AppService --> LogService
    DomainService --> LogService

    %% Data Stores & External Services
    subgraph "Data & External Services"
        direction TB
        DB["Relational Database (PostgreSQL)"]:::datastore
        SendGrid["SendGrid API"]:::external
    end

    %% Configuration
    subgraph "Configuration"
        direction TB
        Settings["Settings & Manage\n(core/settings.py,\nmanage.py)"]:::config
    end

    Settings --> ASGI
    Settings --> WSGI
    Settings --> CeleryApp
    Settings --> DB
    Settings --> MailService

    %% Click Events
    click ASGI "https://github.com/thatdipen/django-sample/blob/main/core/driver/asgi.py"
    click WSGI "https://github.com/thatdipen/django-sample/blob/main/core/driver/wsgi.py"
    click CeleryApp "https://github.com/thatdipen/django-sample/blob/main/core/celery.py"
    click GlobalURLs "https://github.com/thatdipen/django-sample/blob/main/core/interface/urls.py"
    click UserURLs "https://github.com/thatdipen/django-sample/blob/main/core/interface/users/urls.py"
    click Views "https://github.com/thatdipen/django-sample/blob/main/core/interface/users/views.py"
    click Tasks "https://github.com/thatdipen/django-sample/blob/main/core/interface/users/tasks.py"
    click AppService "https://github.com/thatdipen/django-sample/blob/main/core/application/users/services.py"
    click UserModel "https://github.com/thatdipen/django-sample/blob/main/core/domain/users/models.py"
    click DomainService "https://github.com/thatdipen/django-sample/blob/main/core/domain/users/services.py"
    click Migrations "https://github.com/thatdipen/django-sample/tree/main/core/domain/users/migrations/"
    click TextChoices "https://github.com/thatdipen/django-sample/blob/main/core/domain/text_choices.py"
    click MailService "https://github.com/thatdipen/django-sample/blob/main/core/infrastructure/mailing_services/services.py"
    click LogService "https://github.com/thatdipen/django-sample/blob/main/core/infrastructure/log_services/services.py"
    click Templates "https://github.com/thatdipen/django-sample/tree/main/templates/"
    click StaticAssets "https://github.com/thatdipen/django-sample/blob/main/core/static/js/utils.js"
    click Settings "https://github.com/thatdipen/django-sample/blob/main/core/settings.py"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef webapi fill:#DFFFE0,stroke:#28a745,color:#28a745;
    classDef app fill:#FFF5B1,stroke:#FFD33D,color:#8a6d3b;
    classDef domain fill:#FFF0D0,stroke:#E69A00,color:#E69A00;
    classDef infra fill:#FFE0E0,stroke:#d73a49,color:#d73a49;
    classDef datastore fill:#E0E0E0,stroke:#6a737d,color:#6a737d;
    classDef external fill:#F0F0F0,stroke:#6a737d,color:#6a737d;
    classDef config fill:#F5F5F5,stroke:#999,color:#333;
```
