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
Related
- Generate a Diagram from a CodebasePoint it at a repository and it surveys the code the way a new engineer would, then draws what it found.
- Generate a Diagram from TerraformTerraform already describes your infrastructure precisely. The diagram is a rendering of something you have written down, not a guess.
- Generate a Diagram from Kubernetes ManifestsKubernetes YAML contains the whole topology and presents it as several hundred lines in which none of it is visible.
- Generate a Diagram from Docker ComposeA Compose file is already a complete description of a small system. It is just written in a format that hides the shape.