# nautobot/nautobot-app-design-builder architecture

> Architecture diagram of the GitHub repository nautobot/nautobot-app-design-builder, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nautobot/nautobot-app-design-builder
- Repository: https://github.com/nautobot/nautobot-app-design-builder

## Overview

##### Project Type and Purpose
- This is a Nautobot App (a Django‐based plugin) named “Nautobot Design Builder.”
- Purpose: Provide a design-oriented Source of Truth within Nautobot by reading Jinja2-based design templates (from disk or Git), rendering them into Nautobot objects (via Django models/ORM), and managing the full lifecycle (create/update/decommission) through REST/API, UI, and background jobs.

##### Main Components
A. User & Client Tier
- Browser (Admin/UI users)
- CLI/Invoke tasks for local development & management commands
- REST API clients (curl, scripts)

B. Nautobot Core (Django)
- HTTP server / URL router
- Authentication & permissions
- Plugin loader

C. Design Builder Plugin
1. Web/UI Layer
– Django views & templates (templates/nautobot_design_builder/*.html)
– Templatetags & filters for rendering design pages
2. API Layer
– Django REST Framework serializers, views, URLs under `api/`
3. Model Layer
– Django models & migrations (models.py + migrations/)
– ChangeRecord, ChangeSet, Deployment models to track lifecycle
4. Job / Task Layer
– Nautobot Jobs (design_job.py)
– Management commands (build_design.py, install_demo_designs.py)
– Background queue (Redis broker)
5. Templating & Rendering
– Jinja2 integration (jinja2.py, jinja_filters.py)
– Loading design templates from local disk or external Git
6. Utilities & Integrations
– Git integration (git.py) for cloning/pulling design repos
– Custom validators, filters, helpers, context builders

D. Persistence & External Services
- SQL Database (PostgreSQL/MySQL) for Nautobot + plugin models
- Redis (cache, broker for async tasks)
- Filesystem (design template directory)
- External Git repositories (design files source)

##### Relationships & Data Flow
1. UI Request Flow
[Browser] --(HTTPS)--> [Nautobot Core / Plugin Views]
[Plugin Views] --> ORM --> [SQL Database]
[Views] render Jinja2 templates (from disk/Git) into HTML pages

2. REST API Flow
[Client] --(HTTPS/JSON)--> [API Endpoints]
[API Views] --(deserialize/serialize)--> [Models/DB]

3. Design Build Lifecycle
[User triggers build] via UI or CLI --> [Management Command / Job]
[Job Scheduler] enqueues task in Redis --> [Worker]
[Worker] loads templates + input data --> [Jinja2 Engine] --> produces object definitions
[Worker] applies creations/updates/decommissions via ORM --> [DB]
[Worker] records ChangeRecords/ChangeSets in DB

4. Git Integration
[Plugin Git module] <--(Git clone/pull)-- [External Git Repo]
Local template files updated on disk --> used by Jinja2 Engine

##### Architectural Patterns & Principles
- MVC/MVT (Django) separation: templates, views, models
- Plugin modularization: clear API, UI, job, and model sub-packages
- Asynchronous job queue for long-running design builds
- Template-based code generation (Jinja2)
- External Source of Truth via Git integration

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User & Client Tier
    subgraph "User & Client Tier"
        direction TB
        Browser["Browser (UI)"]:::frontend
        CLI["CLI / Management Commands"]:::frontend
        APIClient["REST API Clients"]:::frontend
    end

    %% Nautobot Core & Plugin
    subgraph "Nautobot Core + Design Builder Plugin"
        direction TB

        %% Web/UI Layer
        subgraph "Web/UI Layer"
            direction TB
            Views["Django Views"]:::frontend
            Templates["HTML Templates"]:::frontend
            Templatetags["Template Tags & Filters"]:::frontend
        end

        %% API Layer
        subgraph "API Layer"
            direction TB
            APIUrls["API URL Routing"]:::frontend
            APIViews["API Views"]:::frontend
            Serializers["Serializers"]:::frontend
        end

        %% Model Layer
        subgraph "Model Layer"
            direction TB
            Models["Django Models"]:::backend
            Migrations["Database Migrations"]:::backend
        end

        %% Job / Task Layer
        subgraph "Job / Task Layer"
            direction TB
            JobDef["Nautobot Job Definition"]:::backend
            BuildCmd["build_design Command"]:::backend
            DemoCmd["install_demo_designs Command"]:::backend
            RedisBroker["Redis Broker"]:::datastore
            Worker["Worker"]:::backend
        end

        %% Templating & Rendering
        subgraph "Templating & Rendering"
            direction TB
            JinjaEngine["Jinja2 Engine"]:::backend
            JinjaFilters["Jinja2 Filters"]:::backend
            TemplateContent["Template Content Helpers"]:::backend
        end

        %% Utilities & Integrations
        subgraph "Utilities & Integrations"
            direction TB
            GitIntegration["Git Integration"]:::backend
            ContextBuilders["Context Builders"]:::backend
            Validators["Custom Validators"]:::backend
            Helpers["Helpers"]:::backend
            Filters["Filters"]:::backend
        end

        %% Plugin Registration
        subgraph "Plugin Registration & Config"
            direction TB
            Ext["Extension Hooks"]:::backend
            AppConfig["App Config Schema"]:::backend
            Navigation["Navigation Integration"]:::backend
        end

        %% Test Data
        Tests["Tests & Test Data"]:::backend
    end

    %% Data Stores
    subgraph "Persistence & External Services"
        direction TB
        SQLDB["SQL Database"]:::datastore
        RedisCache["Redis Cache"]:::datastore
        FileSystem["Filesystem (Templates Dir)"]:::datastore
        ExternalGit["External Git Repo"]:::external
    end

    %% Flows
    Browser -->|"HTTPS"| Views
    Views -->|"ORM"| Models
    Views -->|"renders"| Templates

    APIClient -->|"HTTPS/JSON"| APIUrls
    APIUrls --> APIViews
    APIViews -->|"ORM"| Models
    APIViews -->|"serialize/deserialize"| Serializers

    CLI --> JobDef
    CLI --> BuildCmd
    CLI --> DemoCmd

    JobDef --> RedisBroker
    BuildCmd --> RedisBroker
    DemoCmd --> RedisBroker
    RedisBroker --> Worker
    Worker --> JinjaEngine
    Worker -->|"records"| Models

    JinjaEngine --> Templates
    JinjaEngine --> TemplateContent
    JinjaEngine --> ContextBuilders
    JinjaEngine --> JinjaFilters
    Models -->|"SQL"| SQLDB

    GitIntegration -->|"clone/pull"| ExternalGit
    GitIntegration --> FileSystem
    JinjaEngine --> FileSystem

    %% Click Events
    click Views "https://github.com/nautobot/nautobot-app-design-builder/blob/develop/nautobot_design_builder/views.py"
    click Templates "https://github.com/nautobot/nautobot-app-design-builder/tree/develop/nautobot_design_builder/templates/nautobot_design_builder/"
    click Templatetags "https://github.com/nautobot/nautobot-app-design-builder/blob/develop/nautobot_design_builder/templatetags/utils.py"
    click APIUrls "https://github.com/nautobot/nautobot-app-design-builder/blob/develop/nautobot_design_builder/api/urls.py"
    click APIViews "https://github.com/nautobot/nautobot-app-design-builder/blob/develop/nautobot_design_builder/api/views.py"
    click Serializers "https://github.com/nautobot/nautobot-app-design-builder/blob/develop/nautobot_design_builder/api/serializers.py"
    click Models "https://github.com/nautobot/nautobot-app-design-builder/blob/develop/nautobot_design_builder/models.py"
    click Migrations "https://github.com/nautobot/nautobot-app-design-builder/tree/develop/nautobot_design_builder/migrations/"
    click JobDef "https://github.com/nautobot/nautobot-app-design-builder/blob/develop/nautobot_design_builder/design_job.py"
    click BuildCmd "https://github.com/nautobot/nautobot-app-design-builder/blob/develop/nautobot_design_builder/management/commands/build_design.py"
    click DemoCmd "https://github.com/nautobot/nautobot-app-design-builder/blob/develop/nautobot_design_builder/management/commands/install_demo_designs.py"
    click JinjaEngine "https://github.com/nautobot/nautobot-app-design-builder/blob/develop/nautobot_design_builder/jinja2.py"
    click JinjaFilters "https://github.com/nautobot/nautobot-app-design-builder/blob/develop/nautobot_design_builder/jinja_filters.py"
    click TemplateContent "https://github.com/nautobot/nautobot-app-design-builder/blob/develop/nautobot_design_builder/template_content.py"
    click GitIntegration "https://github.com/nautobot/nautobot-app-design-builder/blob/develop/nautobot_design_builder/git.py"
    click ContextBuilders "https://github.com/nautobot/nautobot-app-design-builder/blob/develop/nautobot_design_builder/context.py"
    click Validators "https://github.com/nautobot/nautobot-app-design-builder/blob/develop/nautobot_design_builder/custom_validators.py"
    click Helpers "https://github.com/nautobot/nautobot-app-design-builder/blob/develop/nautobot_design_builder/helpers.py"
    click Filters "https://github.com/nautobot/nautobot-app-design-builder/blob/develop/nautobot_design_builder/filters.py"
    click Ext "https://github.com/nautobot/nautobot-app-design-builder/blob/develop/nautobot_design_builder/ext.py"
    click AppConfig "https://github.com/nautobot/nautobot-app-design-builder/blob/develop/nautobot_design_builder/app-config-schema.json"
    click Navigation "https://github.com/nautobot/nautobot-app-design-builder/blob/develop/nautobot_design_builder/navigation.py"
    click Tests "https://github.com/nautobot/nautobot-app-design-builder/tree/develop/nautobot_design_builder/tests/"

    %% Styles
    classDef frontend fill:#BBE1FA,stroke:#0C2D48,color:#000
    classDef backend fill:#B2F2BB,stroke:#0C5814,color:#000
    classDef datastore fill:#FFD8A8,stroke:#C05600,color:#000
    classDef external fill:#D3D3D3,stroke:#555,color:#000
```
