Boxes and Lines

boxes-and-lines Pirate Software

tag Status s
  Done(green)
  Doing(yellow)
  Todo(red)
  NA(gray) default

active-tag Status

MobileApp | s:Todo
  -> API

WebSite | s:Doing
  -> API

[Backend]
  API | s:Doing
    -> DB
    -> AuthVendor

  DB | s:Done

AuthVendor

Overview

Boxes and lines is a general-purpose node-edge diagram for modeling systems, architectures, and relationships. Nodes are connected with labeled arrows, organized into nested groups, and annotated with color-coded tags.

Unlike more specialized diagram types (infra for traffic simulation, C4 for system context), boxes-and-lines is intentionally flexible. Node shapes are inferred from names — a node called “UserDB” renders as a cylinder, “Redis” as a diamond, “OrderQueue” as a hexagon.

Declaration

boxes-and-lines Optional Title

The first line declares the diagram type and optional title.

Nodes

Nodes are created explicitly or implicitly when referenced in edges.

Explicit nodes

API Gateway | description: Main entry point
UserDB

A name on its own line creates a node. Pipe metadata is optional.

Implicit nodes

API Gateway -routes-> UserService

If UserService hasn’t been declared yet, it’s created automatically from the edge.

Pipe metadata

API Gateway | t: Backend, description: Main entry point

Metadata uses pipe syntax with key: value pairs separated by commas. Common keys:

• Tag aliases (e.g., t: Backend where t is a tag alias)
• description — shown as a subtitle on the node

Shape inference

Node shapes are inferred from names:

Edges

Directed edges

A -> B                    // unlabeled
A -routes-> B             // labeled

Bidirectional edges

A <-syncs-> B             // bidirectional with label
A <-> B                   // bidirectional unlabeled

Indented shorthand

When a node has multiple outbound edges, indent them below:

API Gateway
  -routes-> UserService
  -routes-> ProductService
  -routes-> OrderService

This is equivalent to writing three separate edge lines with API Gateway as the source.

Edge metadata

SessionCache <-syncs-> ProductDB | p: Medium

Edges support pipe metadata, typically for tag values.

Groups

Groups visually contain nodes in a dashed rectangle.

Basic groups

[AWS us-east-1]
  API Gateway
  UserService
  ProductDB

Nested groups (max 2 levels)

[AWS us-east-1]
  [Compute]
    API Gateway
    UserService
  [Data]
    UserDB
    ProductDB

Group-to-group edges

Groups can be edge endpoints:

[Frontend] -> [Backend]

Tags

Tags add colored metadata dimensions for filtering and visual grouping.

Declaring tags

tag Team t Backend(blue), Frontend(green), Platform(purple)
tag Priority p High(red), Medium(orange), Low(gray)

Format: tag Name alias Value1(color), Value2(color), ...

Assigning tags

Use the alias in pipe metadata:

API Gateway | t: Backend
UserDB | t: Platform

Filtering

active-tag Team           // color nodes by Team tag
hide priority:Low         // hide nodes tagged Low priority

Options

Comments

// This is a comment

Only // comments are supported.

Complete Example

boxes-and-lines Microservices

tag Team t Backend(blue), Frontend(green), Infra(purple)
active-tag Team
direction LR

WebApp | t: Frontend
  -> API Gateway

API Gateway | t: Infra
  -auth-> AuthService
  -data-> DataService

AuthService | t: Backend
  -> UserDB

DataService | t: Backend
  -> PostgreSQL
  -> Redis

UserDB | t: Infra
PostgreSQL | t: Infra
Redis | t: Infra

[Cloud]
  [Services]
    API Gateway
    AuthService
    DataService
  [Storage]
    UserDB
    PostgreSQL

Redis <-cache-> DataService