dumbdiagrams. GitHub Get started Architecture diagrams as code for AI-first teams. Let an LLM write reviewable source, then refine the result on your own machine.
Running the CLI… the next step unlocks when the project is ready.
Your cloud. Your call.
Write a normal technical request. The agent interprets the architecture, produces reviewable .dgm code, and Dumb Diagrams renders the result.
A visitor resolves the site through DNS and loads it from a CDN backed by the bucket that stores the website files.
HUMAN PROMPT ENGINE INTERPRETATION .DGM CODE RESULTCreate a simple AWS static website delivery diagram. Show a website visitor, DNS, a content delivery service, and the bucket that stores the website files.
# Architecture brief ## Goal Show a simple AWS static website delivery path from an external website visitor through DNS and content delivery to the bucket that stores the site files. ## Explicit requirements - A website visitor is shown outside AWS. - DNS, a content delivery service, and the website-files bucket are shown in AWS. ## Relationships and containment - The visitor sends a site lookup to DNS; DNS resolves to the content delivery service; the content delivery service fetches website files from the bucket. ## Inferred decisions and exclusions - Route 53 represents DNS, CloudFront represents content delivery, and S3 Bucket represents website file storage, using the canonical AWS catalog types.
dgm 1
diagram aws-easy-static-website-delivery { grammar aws flow lr title "AWS static website delivery"
aws.cloud aws_cloud "AWS Cloud" {
aws.route-53 dns "DNS" {}
aws.cloudfront cdn "Content delivery" {}
aws.simple-storage-service-bucket site_bucket "Website files" {}
}
cloud-agnostic.client visitor "Website visitor" {}
visitor -> dns { id visitor_dns label "site lookup" step 1 }
dns -> cdn { id dns_cdn label "resolve" step 2 }
cdn -> site_bucket { id cdn_bucket label "fetch files" step 3 }
}
Factory sensors stream readings through IoT Core and Kinesis to a Lambda that stores time series in Timestream and raises SNS alerts.
HUMAN PROMPT ENGINE INTERPRETATION .DGM CODE RESULTDraw a left-to-right AWS architecture for factory IoT telemetry. A factory sensor fleet sends readings to AWS IoT Core, which routes them to Kinesis Data Streams. A Lambda consumer normalizes each reading and writes time-series data to Amazon Timestream; it also sends threshold alerts to Amazon SNS. An external operations dashboard reads from Timestream. Show the returned telemetry path from Timestream to the dashboard. Keep the sensor fleet and dashboard outside AWS Cloud, and all AWS services inside AWS Cloud. Use automatic layout and add no other services.
# Architecture brief ## Goal Draw a left-to-right AWS factory IoT telemetry architecture with external factory sensors and an external operations dashboard. ## Explicit requirements - The sensor fleet sends readings to AWS IoT Core, which routes them to Kinesis Data Streams. - A Lambda consumer normalizes each reading, writes time-series data to Amazon Timestream, and sends threshold alerts to Amazon SNS. - The external dashboard reads returned telemetry from Timestream. - Use automatic layout, put all AWS services inside AWS Cloud, keep the sensor fleet and dashboard outside AWS Cloud, and add no other services. ## Relationships and containment - Factory sensor fleet → IoT Core → Kinesis Data Streams → Lambda normalizer. - Lambda sends normalized time-series data to Timestream and threshold alerts to SNS. - Timestream returns telemetry to the external operations dashboard. - AWS services are inside AWS Cloud; the sensor fleet and dashboard are outside. ## Inferred decisions and exclusions - The generic client actor represents the external sensor fleet and the external dashboard because the AWS catalog supplies actors through cloud-agnostic types.
dgm 1
diagram aws-medium-factory-iot-telemetry { grammar aws flow lr title "Factory IoT telemetry"
aws.cloud aws_cloud "AWS Cloud" {
aws.aws-iot-core iot_core "AWS IoT Core" {}
aws.kinesis-data-streams stream "Kinesis Data Streams" {}
aws.aws-lambda normalizer "Normalize readings" {}
aws.timestream timestream "Amazon Timestream" {}
aws.simple-notification-service sns "Amazon SNS" {}
}
cloud-agnostic.client sensor_fleet "Factory sensor fleet" {}
cloud-agnostic.client dashboard "Operations dashboard" {}
sensor_fleet -> iot_core { id sensors_iot label "sensor readings" step 1 }
iot_core -> stream { id iot_stream label "route readings" step 2 }
stream -> normalizer { id stream_lambda label "stream records" step 3 }
normalizer -> timestream { id lambda_timestream label "normalized time-series" step 4 }
normalizer -> sns { id lambda_sns label "threshold alerts" step 4 }
timestream -> dashboard { id timestream_dashboard label "read telemetry" step 5 }
}
An upload API that stores originals, queues thumbnail jobs for a processor, and serves both images through a CDN.
HUMAN PROMPT ENGINE INTERPRETATION .DGM CODE RESULTCreate an AWS image thumbnail pipeline. An uploader submits an image through an API; the upload handler stores the original and queues a thumbnail job; a processor creates a thumbnail; a content delivery service serves both original and thumbnail images.
# Architecture brief ## Goal Create an AWS pipeline in which an uploader submits images through an API, originals are stored, thumbnail work is queued and processed, and a content delivery service serves both image variants. ## Explicit requirements - An uploader submits an image through an API. - An upload handler stores the original and queues a thumbnail job. - A processor creates a thumbnail. - A content delivery service serves original and thumbnail images. ## Relationships and containment - Uploader → API Gateway → Lambda upload handler. - Upload handler stores the original in the image bucket and queues work in SQS; the queue invokes a Lambda thumbnail processor; the processor writes the thumbnail to the image bucket. - CloudFront fetches the original or thumbnail from the image bucket and serves the images to the uploader/viewer. ## Inferred decisions and exclusions - Use one S3 bucket for original and thumbnail objects because the request describes a single original store and does not request a separate output bucket. - API Gateway is the API entry point and Lambda represents the named upload handler and thumbnail processor.
dgm 1
diagram aws-medium-image-thumbnail-pipeline { grammar aws flow lr title "AWS image thumbnail pipeline"
aws.cloud aws_cloud "AWS Cloud" {
aws.api-gateway api "Upload API" {}
aws.aws-lambda upload_handler "Upload handler" {}
aws.simple-storage-service-bucket assets_bucket "Image assets" {}
aws.simple-queue-service jobs_queue "Thumbnail jobs" {}
aws.aws-lambda processor "Thumbnail processor" {}
aws.cloudfront cdn "Content delivery" {}
}
cloud-agnostic.client uploader "Uploader / viewer" {}
uploader -> api { id uploader_api label "image upload" step 1 }
api -> upload_handler { id api_upload_handler label "upload request" step 2 }
upload_handler -> assets_bucket { id handler_original label "store original" step 3 }
upload_handler -> jobs_queue { id handler_queue label "queue job" step 3 from e to w }
jobs_queue -> processor { id queue_processor label "thumbnail job" step 4 }
processor -> assets_bucket { id processor_thumbnail label "store thumbnail" step 5 from e to w }
cdn -> uploader { id uploader_cdn label "deliver images" step 7 }
assets_bucket -> cdn { id cdn_origin label "serve assets" step 6 from e to w }
}
.dgm source, then open it in Studio to refine and ship it.Create one with an agent ↗Give the model the architecture rather than a canvas full of coordinates. The engine handles placement and connector routes, producing a repeatable first render that you can adjust.
Inside the engineThe document, catalog, and saved view determine the output. Routes are scored for obstacles, crossings, bends, and distance, with A* search when simple paths are blocked. Dense cases raise warnings so you know where the result needs review.
Move a service, choose a port, or draw a manual route in Studio. Your positions and visual overrides stay in the .dgm file, so the next render preserves your decisions.
Ask an agent to write compact source instead of issuing repeated shape-by-shape MCP tool calls. Letting the engine handle layout can reduce token use and make lighter models practical. Savings depend on the model, context, and workflow.
A few things to know before you start.
Your architecture lives in a readable .dgm file, not a collection of hand-placed shapes. A large language model (LLM) can draft or update that source through a coding agent. The deterministic engine handles layout and routing. Review the diff in Git and refine the result in Studio. No built-in model or AI subscription is required. Explore the LLM-first workflow.
No, but one is useful for a first draft. Run dumbdiagrams init from the directory where you want the new project folder, then give the agent AGENTS.md and the shared .dumbdiagrams/ instructions. Codex, Claude Code, Cursor, Gemini CLI, or another coding agent can write a solid starting point. You can also write .dgm files yourself or edit them in Studio.
On your machine, as portable .dgm files wherever you choose. Studio runs locally at 127.0.0.1 and saves the selected file directly; it is not tied to the repository where you started it. If you use the standalone browser editor instead, it keeps work in browser storage until you download a copy. More about the two modes.
Yes. AWS was the starting point, and the catalog now includes Azure, Google Cloud, and cloud-agnostic assets too. Support for those may be less polished than the AWS workflow. If something you need for your provider is missing, contributions are welcome: see CONTRIBUTING.md.
You describe the services, boundaries, and connections, and Dumb Diagrams lays them out for you. You can then refine the result. The engine keeps placement, icon alignment, and arrow routing consistent, so an agent’s draft won’t leave you with drifting icons or arrows taking odd paths. An agent may give you a different draft each time, but the same .dgm source always renders the same way. The layout rules mostly follow AWS architecture guidance, with a few design choices of our own. It’s built for architecture diagrams, so it won’t cover general illustration, track your live infrastructure, or give you a hosted workspace for editing together.
Yes. Dumb Diagrams is released under AGPL-3.0-only. The provider icons come with their own terms. You’ll find the details in the project license and icon notices.
