Start
Architecture diagrams you can play and test
Last updated
Proschi is a text language for architecture diagrams: you write the services and the requests between them, and Proschi draws the diagram, plays each request and checks the design against the traffic you expect.
The example below is a complete design for a link shortener. Hover, tap or tab to a line to see what it does and what it draws.
title "Short links"
user "Reader" [Browser]
api "Links API" [REST API] x3
cache "Link cache" [Redis]
db "Links DB" [PostgreSQL] x2
user -> api : HTTPS
api -> cache : RESP
api -> db : SQL
usecase "Open a link" {
user -> api : GET /r/abc
api -> cache : GET link:abc
api -> db : SELECT link
api --> user : 302
}
traffic {
"Open a link" 2k rps
}
requirements {
p99 "Open a link" < 50ms
}
title "Short links"The diagram's name. Exported files and the design document use it.user "Reader" [Browser]A node: an id, the name on its box, and a tech stack from the catalog in square brackets.api "Links API" [REST API] x3x3runs three replicas of the API. The simulation splits its load between them.cache "Link cache" [Redis][Redis]makes this a cache. The tech stack sets how fast a node answers and how much load it takes.db "Links DB" [PostgreSQL] x2x2keeps a second database, so one failed node doesn't take every link down with it.user -> api : HTTPSA connection draws an arrow. The text after the colon is its label.api -> cache : RESPLabels are free text. Name the protocol:RESPis the one Redis speaks.api -> db : SQLUse case steps can only travel along connections, so draw one for every call the API makes.usecase "Open a link" {A use case is one request, step by step. Press Play to watch it move through the diagram.user -> api : GET /r/abcA step: who calls whom, and with what. It travels theuser -> apiarrow.api -> cache : GET link:abcThen the API looks the link up in the cache.api -> db : SELECT linkAnd reads the database. Each step adds load to the node it calls.api --> user : 302-->is the answer going back, with its status code.traffic {How many requests per second the use case gets. The simulation sends them through every step.requirements {A requirement the design must meet: 99% of requests answered within 50 ms. The editor checks it as you type.
Try it: open the example in the editor and change
x3tox1onapi. The p99 requirement fails in Results, because one replica cannot take 2k rps.
The text is the design. It sits next to your code, you review it in pull requests, and the layout follows when you add a line. The editor runs in your browser and keeps your diagrams there. Why Proschi says more about when it fits.
What to read next #
- Quickstart: your first diagram in two minutes, played and tested.
- Language overview: every statement, with a link to the page that explains it.
- Org diagrams: one box per team, and which team cannot take the traffic you send it.
- How the model works: what the simulation counts, and how far to trust its numbers.