Docs menu
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 #

Edit this page on GitHub