Generate an architecture diagram from a Python project.
Python projects hide their structure in decorators and imports, both of which are readable and neither of which is visible from a directory listing.
What it reads
pyproject.toml or requirements files to establish dependencies and entry points, then the import graph from those entry points. Framework conventions carry a lot of the meaning: FastAPI and Flask route decorators mark the API surface, Django apps and models give both structure and the data model, Celery task decorators identify asynchronous work, and SQLAlchemy or Django ORM definitions identify what writes to which store.
How Python becomes components
Components are drawn at the level of packages and modules that own something, not at the level of every file. A module that defines routes is an API component; one that defines tasks is a worker; one that defines models is the data access boundary. External dependencies from the manifest that represent infrastructure, a database driver, a queue client, an HTTP client for a known service, become external or data tier nodes with edges from whatever imports them.
Why the layout can be trusted
The agent reads the files listed above and emits a semantic graph: components, the tier each belongs to, and the edges between them, with no coordinates anywhere. The ELK layout engine then computes positions and orthogonal edge routing. This is why the output cannot come back with boxes overlapping or arrows crossing through cards, which is the usual failure when a language model is asked to place things on a canvas itself.
Async work is usually the missing half
Most Python service diagrams drawn by hand show the request path and omit the Celery tasks entirely, which is where a surprising amount of the actual behaviour lives. Reading task decorators puts those on the diagram, along with what enqueues them, and that is frequently the part a reviewer has never seen laid out.
Your code stays on your machine
It runs on your machine. With a local Ollama model nothing leaves the laptop at all, and with your own API key the file contents go to the provider you chose and never through us. For a source that is your actual codebase, that distinction is usually the deciding one.
Python to diagram
| In the code | In the diagram |
|---|---|
| pyproject.toml, requirements.txt | Dependencies and entry points |
| FastAPI or Flask route decorators | API surface, application tier |
| Django apps | Components, with their models |
| Celery task decorators | Worker components |
| SQLAlchemy or Django models | Data tier edges |
| Import graph from entry points | Edges between components |
| Redis, Kafka, boto3 clients | External and data tier nodes |
| tests/, conftest.py | Not drawn |
The prompt
Questions
Does it run my code?
No. It reads files. Nothing is imported or executed, which matters for a codebase whose imports have side effects.
Does it work with Django specifically?
Well, because Django's conventions are strong: apps, models and URL configuration each say something structural, so there is less inference and more reading.
Will it draw the database schema too?
It can draw an ER diagram from the models as a separate diagram. Combining a service architecture and a full entity model in one picture makes both harder to read.
What about notebooks?
They are read as context but rarely produce useful components, since a notebook is usually a script rather than a piece of architecture.
Related
- Generate a Diagram from a TypeScript ProjectTypeScript projects usually have a real structure and a directory layout that obscures it, mostly because everything is a file that exports something.
- Generate a Diagram from a Go ProjectGo's package structure is unusually honest, which makes it one of the better languages to read architecture out of.
- Generate a Diagram from a Rust ProjectCargo already knows the crate graph, so a workspace diagram is mostly a rendering of something the build system computes anyway.
- Generate a Diagram from a Django ProjectDjango's conventions are strong enough that most of the architecture is declared rather than implied, which makes it one of the easiest sources to read accurately.
Last updated