On this page
Language
Proschi language reference
Last updated
A Proschi document describes an architecture (nodes, groups and the connections between them) and its use cases (request flows, step by step) as plain text. A mistake never stops the diagram: each problem is reported with its line and column, and the rest still renders.
title "E-Commerce Platform"
group vpc "AWS VPC" {
gateway "API Gateway" [AWS API Gateway] @Platform
orders "Order Service" [REST API] @Orders "Handles orders"
}
ordersDb "Orders DB" [PostgreSQL]
events "OrderEvents" [Kafka]
gateway -> orders : HTTP
orders -> ordersDb : SQL
orders -> events : Publish
usecase "Create order" {
gateway -> orders : POST /api/orders json {
"sku": "A1"
}
alt "Created" {
par {
orders -> ordersDb : INSERT order
orders ->> events : PUBLISH OrderCreated {"orderId": "o-1"}
}
orders --> gateway : 201 {"status": "pending"}
} alt "Invalid payload" {
orders --> gateway : 400 {"error": "sku required"}
} alt "DB down" {
orders -x ordersDb : INSERT order
orders --> gateway : 503
}
}
Try it: pick "Create order › DB down" and press Play. The failed insert and the 503 are drawn in red.
The architecture is written once, and any number of use cases play over it. The web editor, the command line and the editor plugins report the same problems. Format code in the editor, or proschi fmt, indents blocks by two spaces and lines up similar lines in columns.
Statements #
Each line of a document is one statement. Square brackets mark optional
parts, except in a tech stack such as [Redis], where they are literal.
| Statement | Syntax | Where | Details |
|---|---|---|---|
| Title | title "Text" ["Summary"] |
top level | The second string is a one-line summary. |
| Node | id ["Name"] [Tech] [@team] ["Description"] [x3] … |
top level, group | Nodes |
| Group | group id ["Name"] [Style] … { … } |
top level, group | Groups |
| Connection | a -> b [.tag] [: label] |
top level, group | Connections |
| Type | [abstract] type Name [extends Parent] { … } |
top level | Component types |
| Legend | legend { … } |
top level | Colors and legend |
| Direction | direction down|right|up|left |
top level, group | Steering the layout |
| Ordered layout | layout ordered |
top level | Steering the layout |
| Use case | usecase "Name" ["Description"] { … } |
top level | Use cases |
| Scenario | alt "Name" [when "condition"] { … } |
use case, scenario | Scenarios |
| Parallel steps | par { … } |
use case, scenario | Parallel steps |
| Import | import "infra.proschi" |
top level | Imports |
| Constant | let peak = 120k rps, used as $peak |
top level | Constants |
| System | system id ["Name"] [@team] … { … } |
top level, group | The system block |
| Traffic | traffic { … } |
top level | Traffic |
| Capacity | capacity { … } |
top level | Capacity |
| Entity | entity Name [in store] { … } |
top level | Entities |
| Decision | decision "Title" { … } |
top level | Decisions |
| Requirements | requirements { … } |
top level | Requirements |
| Test | test "Name" { … } |
top level | Tests |
| What-if | whatif "Name" { … } |
top level | What-ifs |
| Comment | # … |
anywhere | To the end of the line. A # inside quotes or a JSON payload is text, and so is a hex color after color. |
The grammar has every statement in EBNF.
Pages in this section #
- Nodes, groups and connections: ids, names, tech stacks, replicas and owners.
- Component types: what a tech stack names, your own types, and the operations a node takes.
- Colors, legend and layout: colors, tags, layout hints and what canvas edits write.
- Use cases: step arrows, labels, payloads, fan-out, reads and writes.
- Scenarios: success and failure paths, parallel steps and endpoint groups.
- Imports: split a design across files, local or remote.
- Org diagrams and team systems: one box per team, with a contract.
- High-level design: quantities, traffic, capacity, entities and decisions.
- Requirements and tests: checks on numbers and on request flows, and selectors.
- Grammar: the whole syntax in EBNF.