djangomap

Turn any Django project into a beautiful, interactive architecture diagram.

Models · Views · URLs · Celery tasks · Beat schedules · Signals · Middleware · Admin · Serializers

Why · Quick start · The three tabs · CLI · CI · How it works · License

Why

You join a Django codebase with 40 apps. Which view serves /checkout/? What fires capture_payment? Which models does the admin actually expose? Answering these means grepping across dozens of files.

djangomap reads your project without importing it and produces a single HTML file that answers those questions visually — plus it flags N+1 risks, circular app dependencies and missing related_names along the way.

Quick start

pip install -e ./djangomap
djangomap /path/to/your/project -o diagram.html
open diagram.html

That's it. For the full experience, add source links:

djangomap . \
  --title "My Shop" \
  --editor vscode \
  --repo-url https://github.com/me/myshop \
  --branch main \
  -o diagram.html

Or use it as a library:

from djangomap import scan_project, render_html
from djangomap.analysis import analyse

proj = scan_project("/path/to/project")
data = proj.to_dict()
data["health"] = analyse(proj)

render_html(data, "diagram.html")
print(proj.stats())        # {'model': 8, 'view': 8, 'url': 12, ...}

The three tabs

1 · Apps — what is in each app

Every app becomes its own board with a dedicated colour. Inside, cards are grouped by kind and show a useful summary line: a model's field count, a URL's handler and name=, a view's base class, a task's argument signature, a beat entry's schedule.

Relationship wires are routed through the gutters between boards, so they never cut across cards — including relations that span apps.

Click any card to open the detail panel: full field list with on_delete and related_name, the Meta class, properties, methods, cyclomatic complexity, detected issues, and every relation as a clickable link so you can walk the graph.

Selecting a node also dims everything unrelated, leaving just its neighbourhood lit:

Drag a board header to rearrange · scroll to zoom · F to fit · Esc to clear · collapse individual boards or all at once for a bird's-eye view

2 · Flow — how the system fits together

Four architecture views, switchable from the toolbar.

Request Lifecycle

The full path of an HTTP request through parallel lanes: Middleware → URLconf → View → Serializer/Form → Model, with a separate lane for async Celery work.

App Dependencies

Which apps import which, derived from real import statements, annotated with reference counts. Circular dependencies show up immediately.

Celery Pipeline

Producers (views, signals, beat entries, management commands) → Broker → Workers → Result backend, including task-to-task chains.

Data Model

A full ERD: every model with its fields, and the FK / M2M / O2O relations between them, grouped by app.

3 · Health — what is wrong

A 0–100 score plus issues grouped by check. Click any issue to jump straight to that card in the Apps tab. Cards with problems get a coloured dot.

Below the issue list, a per-app breakdown shows where the debt is concentrated:

Checks

view.unauth and model.orphan are heuristic and can be noisy on real projects, which is why they are info and barely affect the score.

Responsive

The whole UI adapts down to a 320px phone.

Pinch-to-zoom and touch panning work on both canvases. Tablet reflows to two columns:

CLI reference

djangomap [path] [options]

Text exports

Paste straight into a README or PR comment:

djangomap . --format mermaid-erd      # GitHub renders this natively
djangomap . --format mermaid-flow
djangomap . --format dot | dot -Tsvg -o graph.svg
djangomap . --markdown report.md

erDiagram
    Product {
        Char title
        Decimal price
        ForeignKey category FK
        ManyToMany tags FK
    }
    Product ||--o{ Category : "category"
    Product }o--o{ Tag : "tags"

CI integration

Fail the build when architectural errors appear:

# .github/workflows/architecture.yml
name: Architecture
on: [push, pull_request]

jobs:
  djangomap:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: "3.12" }
      - run: pip install -e ./djangomap
      - run: djangomap . --fail-on error -o diagram.html
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: architecture-diagram
          path: diagram.html

Every PR then carries a downloadable, up-to-date diagram of the codebase.

Keyboard shortcuts & permalinks

The active tab, flow view, selected node and every filter are encoded in the URL #hash. Send the link to a teammate and they land on exactly the same view.

What gets extracted

Relationship types

Large and non-standard layouts

djangomap does not assume that every app is a top-level directory with a flat models.py. It discovers apps structurally, so the following all work:

Nested app namespaces. A src/ root with apps under several packages — apps/crm/, auths/users/, and a bare core/ — is detected as 32 separate apps, not 3. Boards are labelled with the short name and grouped in the sidebar by their prefix.

Apps as packages. A directory is recognised as an app when it has a migrations/ folder, an apps.py declaring an AppConfig, or the usual module set. Django modules may be packages instead of files:

apps/messenger/
├── models/messenger.py          → models
├── serializers/_chat_serializer.py  → serializers
├── apis/_chat_api.py            → views
├── urls/{regular_url,socket_routing}.py → urls
└── consumers/messenger.py       → WebSocket consumers

Each file's role is derived from its own name or its parent package, so core/models/base.py and crm/models.py are both read as models.

Channels. websocket_urlpatterns and AsyncJsonWebsocketConsumer subclasses are extracted as a dedicated consumer kind and routed via .as_asgi().

Tests are excluded by default. A mirrored src/tests/apps/** tree, plus test_*.py, conftest.py, factories.py and simulation/, is skipped so fixtures never inflate your model or view counts. Pass --include-tests to include them.

INSTALLED_APPS drives the layout. djangomap locates your settings module by content, not by a hard-coded path — settings.py, config/settings/base.py and web_config/environments/common.py are all found automatically — then reads INSTALLED_APPS and treats it as the authoritative app list. Entries may be plain packages (core), dotted (apps.crm) or AppConfig paths (billing.apps.BillingConfig); all resolve to the right directory. Boards are ordered exactly as declared, and any app found on disk but missing from INSTALLED_APPS is still shown, flagged with a ! in the sidebar.

Boards are partitioned by namespace. On the Apps tab, each namespace gets its own labelled band — apps, auths, root — and masonry packing happens within a band, so apps.crm never ends up sitting next to core in the same row. Projects with a single namespace get no headings. Use --group-by none to switch back to one flat grid.

Wide diagrams stay readable. On the Flow tab, lanes with many nodes wrap into sub-columns rather than stretching into one unreadably long strip.

How it works

scanner.py    walks the tree, parses each .py with ast, emits nodes + edges
analysis.py   runs 16 checks over that graph, scores the project
export.py     renders Mermaid / DOT / Markdown
render.py     inlines the graph JSON + pre-built Tailwind into one HTML file
cli.py        argument parsing and orchestration

Because everything is AST-based, your code is never executed — safe to point at an unfamiliar repository. The trade-off is that dynamically constructed URLconfs or programmatically generated models won't be seen. For those, the graph is a very good approximation rather than a perfect runtime reflection.

Migrations, node_modules, virtualenvs, caches and static dirs are skipped.

Development

python -m djangomap.cli ./sample_shop -o demo.html    # run against the bundled sample

The Tailwind stylesheet is pre-built at djangomap/tailwind.css. Rebuild it after editing template.html:

npx tailwindcss -c tailwind.config.js -i tw.css -o djangomap/tailwind.css --minify

The repo ships a sample_shop/ Django project (4 apps, 8 models, 6 tasks, DRF, Celery Beat, a management command) used for the screenshots above.

Limitations

• Dynamic URLconfs and runtime-generated models are invisible to static analysis
• Third-party apps are only mapped if they live inside the scanned tree
• related_name reverse accessors that Django creates implicitly are not inferred
• The N+1 check is a heuristic: it flags missing select_related but cannot know whether the template actually traverses the relation

License

Released under the MIT License — free for personal and commercial use.

Copyright (c) 2026 djangomap contributors