Why it works
The .archy format was designed to be human-writable, but it's also an excellent target for language models. The schema is small, regular, and semantic — properties that LLMs handle exceptionally well. In practice, you can describe your system in plain English and get a complete, working .archy file in one prompt.
A language model generating .archy output needs to:
- Map system components to one of 12 node types
- Map interactions to one of 8 edge types
- Produce well-formed JSON
That's a tractable, constrained task. Models rarely hallucinate node or edge types when the full vocabulary is in the prompt. The result is usually correct JSON that opens directly in Archy.
The system prompt
Paste this into your model's system prompt or at the top of your conversation to give the model complete context:
You generate Archy v2 architecture diagram files (.archy format).
## Format
```json
{
"version": "2",
"name": "diagram name",
"description": "one-line summary",
"nodes": [
{
"id": "kebab-case-id",
"type": "<node type>",
"name": "Display Name",
"description": "one-line description",
"_meta": { "key": "value" }
}
],
"edges": [
{
"id": "kebab-case-id",
"from": "source-node-id",
"to": "target-node-id",
"type": "<edge type>",
"label": "HTTPS"
}
],
"groups": [
{
"id": "group-id",
"label": "Group Label",
"type": "logical",
"nodes": ["node-id-1", "node-id-2"]
}
]
}
```
## Node types
- `service` — microservice or backend application
- `api` — named API surface (REST, GraphQL, gRPC)
- `kafka-topic` — a specific Kafka topic (not the cluster)
- `queue` — message queue (RabbitMQ, SQS, Azure Service Bus)
- `database` — any persistent data store (RDBMS, NoSQL, cache)
- `frontend` — web SPA, mobile app, or desktop client
- `batch-job` — scheduled job, ETL, cron task
- `external` — third-party service, external SaaS
- `actor` — human user, team, or external persona
- `gateway` — API gateway, load balancer, reverse proxy
- `broker` — message broker platform (Kafka cluster, RabbitMQ server)
- `datastore` — data lake, warehouse, data platform
## Edge types
- `calls` — synchronous HTTP/RPC/gRPC (solid arrow →)
- `publishes` — producer emits events to topic/queue (solid arrow →)
- `consumes` — consumer reads from topic/queue (dashed arrow, reversed ←)
- `writes` — service writes data to a store (solid arrow →)
- `reads` — service reads data from a store (dashed arrow, reversed ←)
- `streams` — continuous/streaming data flow (thick solid arrow →)
- `triggers` — webhook, scheduler, event-driven execution (dashed arrow →)
- `uses` — catch-all for non-specific dependency (solid arrow →)
## Group types
- `logical` — domain or team boundary (solid teal border)
- `zone` — network or infrastructure zone (dashed indigo border)
## Rules
- All IDs must be unique and use kebab-case
- Edge `from` and `to` must match node IDs in the same file
- `_meta` is optional free-form JSON for infrastructure details
- Do NOT invent new node types or edge types — use only the ones listed above
- Output ONLY the JSON, no explanation
When the user describes a system, produce a complete, valid .archy file.Example prompts
Describing a system from scratch
Generate an Archy diagram for a food delivery app. Customers use a mobile app and a web app. Both talk to an API Gateway. Behind the gateway are: an Orders service, a Restaurant service, a Delivery service, and a Payments service. Orders publishes events to a Kafka topic called order-placed. Restaurant service and Delivery service consume it. Payments service is called synchronously by Orders. All services have their own PostgreSQL databases.
A good model will produce a complete .archy file with all the nodes, edges, and appropriate types.
From a technical document or README
Here's our system architecture README. Convert it to an Archy diagram file:
[paste your README or architecture document]
From an existing diagram description
Our system has these components: [paste Confluence page, architecture decision record, or whiteboard notes]
Create an Archy file from this.
Iterating on an existing file
Here's my current .archy file:
[paste file]
Add a Redis cache that the Orders service reads from and writes to. Also add a CDN in front of the web app.
Example output
Given a simple prompt about an e-commerce checkout flow, a model should produce something like:
{
"version": "2",
"name": "E-Commerce Checkout",
"description": "Payment and order flow for checkout.",
"nodes": [
{ "id": "customer", "type": "actor", "name": "Customer" },
{ "id": "web-app", "type": "frontend", "name": "Web App" },
{ "id": "api-gateway", "type": "gateway", "name": "API Gateway" },
{ "id": "order-service", "type": "service", "name": "Order Service", "_meta": { "team": "commerce" } },
{ "id": "payment-service", "type": "service", "name": "Payment Service", "_meta": { "compliance": "PCI-DSS" } },
{ "id": "order-placed", "type": "kafka-topic", "name": "order-placed" },
{ "id": "notify-service", "type": "service", "name": "Notification Service" },
{ "id": "orders-db", "type": "database", "name": "Orders DB" },
{ "id": "stripe", "type": "external", "name": "Stripe" }
],
"edges": [
{ "id": "e1", "from": "customer", "to": "web-app", "type": "uses" },
{ "id": "e2", "from": "web-app", "to": "api-gateway", "type": "calls", "label": "HTTPS" },
{ "id": "e3", "from": "api-gateway", "to": "order-service", "type": "calls", "label": "HTTPS" },
{ "id": "e4", "from": "order-service", "to": "payment-service", "type": "calls", "label": "HTTPS" },
{ "id": "e5", "from": "payment-service", "to": "stripe", "type": "calls", "label": "HTTPS" },
{ "id": "e6", "from": "order-service", "to": "order-placed", "type": "publishes", "label": "AMQP" },
{ "id": "e7", "from": "notify-service", "to": "order-placed", "type": "consumes" },
{ "id": "e8", "from": "order-service", "to": "orders-db", "type": "writes", "label": "PostgreSQL" }
],
"groups": [
{
"id": "internal",
"label": "Internal Services",
"type": "zone",
"nodes": ["order-service", "payment-service", "notify-service", "orders-db", "order-placed"]
}
]
}Tips for better output
Be specific about interaction types. Instead of "the worker reads from the queue", say "the worker consumes messages from the queue". The model maps language to edge types more reliably with precise verbs.
Name your services explicitly. "Orders service, Payments service" → better output than "a few backend services".
Mention databases per service. "Each service has its own PostgreSQL database" → the model creates separate database nodes and write edges.
Ask for _meta enrichment. "Add team ownership, technology stack, and compliance notes to each node in _meta" produces richer diagrams.
Iterate in steps. Start with the happy path. Then add error queues, monitoring, admin services, and external dependencies in follow-up messages.
Fix and re-ask. If an edge type is wrong or a node is missing, paste the generated file back and say: "Change the edge from X to Y to type publishes. Add a reads edge from the Reports service to the Orders DB."
Using AI to update existing diagrams
You can also use a model to maintain diagrams as your system evolves.
Adding a new service
Here's my current .archy file. We're adding a new Recommendations service that reads from the Products DB and is called by the API Gateway. Add it.
Refactoring a relationship
The Auth service used to be called synchronously. We've migrated to a JWT validation pattern where the API Gateway validates tokens itself. Update the diagram — remove the gateway-to-auth edge and replace it with a reads edge from the gateway to a new jwt-key-store database node.
Splitting a service
We're breaking the monolithic Order Service into Order Management, Order Fulfillment, and Order History. Update the diagram to replace the single Order Service node with the three new services. Order Management publishes to the existing order-placed topic. Order Fulfillment consumes it.
Validating AI-generated output
Archy will render any valid .archy file — unknown node types fall back to a grey node, unknown edge types fall back to a grey arrow. Before committing an AI-generated file:
- Open it in VS Code with Archy — if it renders, the JSON is valid
- Check that node and edge types are from the known list (the detail panel shows the type for each element)
- Verify that edge
from/tovalues match actual node IDs - Check that
groups[].nodesarrays reference real node IDs