Docs menu

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
}
  1. title "Short links" The diagram's name. Exported files and the design document use it.
  2. user "Reader" [Browser] A node: an id, the name on its box, and a tech stack from the catalog in square brackets.
  3. api "Links API" [REST API] x3 x3 runs three replicas of the API. The simulation splits its load between them.
  4. cache "Link cache" [Redis] [Redis] makes this a cache. The tech stack sets how fast a node answers and how much load it takes.
  5. db "Links DB" [PostgreSQL] x2 x2 keeps a second database, so one failed node doesn't take every link down with it.
  6. user -> api : HTTPS A connection draws an arrow. The text after the colon is its label.
  7. api -> cache : RESP Labels are free text. Name the protocol: RESP is the one Redis speaks.
  8. api -> db : SQL Use case steps can only travel along connections, so draw one for every call the API makes.
  9. usecase "Open a link" { A use case is one request, step by step. Press Play to watch it move through the diagram.
  10. user -> api : GET /r/abc A step: who calls whom, and with what. It travels the user -> api arrow.
  11. api -> cache : GET link:abc Then the API looks the link up in the cache.
  12. api -> db : SELECT link And reads the database. Each step adds load to the node it calls.
  13. api --> user : 302 --> is the answer going back, with its status code.
  14. traffic { How many requests per second the use case gets. The simulation sends them through every step.
  15. 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 x3 to x1 on api. 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.

  • 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.

Edit this page on GitHub