Language Reference

FractalForm diagrams are plain-text scripts for animated system diagrams. A minimal diagram can be one edge:

client -> api: GET /users
api -> client: 200 OK

Edges and state updates create components automatically. Add declarations, phases, notes, overlays, artifacts, playback directives, and control blocks only when the diagram needs them.

Declare named topology nodes. Edges and state updates auto-create components, so declarations are only needed for custom labels, shapes, icons, tiers, tags, descriptions, or hierarchy. Examples: Components, Descriptions.

Syntax:

Aliases: c.

Shapes: default, circle, database, hexagon, diamond, note, actor, icon, cloud, browser, server, funnel, code.

Tiers: xl, lg, md (default), sm, xs.

# full declaration
component api "API Gateway" shape:hexagon,xl icon:server,badge [backend, gateway]
component db "PostgreSQL" shape:database,lg icon:postgresql,badge [storage]

# pools and replicas
component workers "Workers" shape:hexagon,many
component replicas "Read Replicas" shape:database,lg,many

# tier-only (default shape)
component important "Important" shape:lg

Descriptions

Add a trailing :, |, ], or } and indented markdown for permanent descriptions. Descriptions render beside the node and are not cleared by --clear.

# guide bar (: marker)
component api "API Gateway" shape:hexagon,xl:
  Handles public HTTP ingress and authentication.

# bracket (] marker)
component policy "Policy" ]
  Never trusts tenant-provided ownership metadata.

# brace (} marker)
component worker "Worker" }
  - uses tools
  - runs in a loop

Key hierarchy

Dots create child components inside a parent. Double dots create related components that render separately but stay visually attached. Examples: Member, Related.

# child components
component app "App"
component app.cpu "CPU"
component app.mem "Memory"

# related (renders separately, visually attached)
component app "App"
component app..logs "App Logs"
app -> app..logs: write logs

Define connections between components. Edges auto-create undeclared components. Examples: Edges, Arrow styles, Chained edges, Fan-out & Fan-in, Bidirectional edges.

Syntax:

# labeled edge
api -> db: SELECT users

# chained edges
client -> api -> db

# mixed arrow types
client -> api --> cache ->> queue

# fan-out
api -> [worker-a, worker-b, worker-c]: dispatch job

# fan-in
[service-a, service-b] -> aggregator: results

# bidirectional
client <-> server: WebSocket message

Edge modifiers

Inline modifiers control edge appearance. Example: Edge Icons & Modifiers.

api -> db <icon:zap>: fast query
db -> api: rows <icon:check #success>
api -> upstream: timeout edge:dropped,#error
api -> db: degraded edge:#warning

Icons support Lucide, brand, and AWS icon names with optional color and size. Declarations use bare icon:name; inline narration uses <icon:name #color size>.

# in edge labels
api -> db: query <icon:database #info>
api -> client: failed <icon:x #error xl>

# in overlays
# overlay: <icon:clock #warning> Token expires

# in declarations
group aws icon:cloud,#info
component api icon:server,badge

Visual metadata on components. Tags do not change behavior. Use them for role, ownership, environment, or status. Optionally colored.

Syntax:

component api "API" [backend, gateway]
component payments "Stripe" [external, payments #info]
component legacy "Legacy API" [deprecated #warning]

Canvas-level annotation (titles, labels, legends, callouts). Not topology. Example: Text.

Syntax:

Aliases: t.

Shapes: rect (default), circle, diamond, hex, ellipse. Stroke modifiers: solid, dashed, dotted.

# inline text
text title "Request Flow" shape:rect,solid,xl,#info
text subtitle "One request through the backend"

# with markdown body
text warning "Dotted ellipse" shape:ellipse,dotted,#warning:
  Text bodies support **Markdown**.
  - headings
  - lists
  - inline `code`

# inside a group
group annotation-zone shape:rect,dashed,#blue
  text:
    Group-level annotation.
  title
end

Set content on a component node. Examples: State, Structured Data, Markdown.

Syntax:

Common structured data shapes (see Content formats):

# text state
api: Processing request

# structured data
api: {
  status: "ok",
  count: 42
}

# markdown body
api:
  Handles **requests**.
  - validates input
  - emits events

# code block with language
api: ```json
{
  "status": "ok",
  "data": [1, 2, 3]
}
```

Label sections of the timeline for navigation. Example: Phases.

Syntax:

# phase: Authentication
# Validates credentials and issues a token.
client -> auth: POST /login

Draw visual boundaries around components and canvas text. Examples: Groups, Nested Groups.

Syntax:

Aliases: g, box, b.

Shapes: rect (default), circle, diamond, hex, ellipse. Inside group bodies, the component keyword is optional.

# named group with members
group "Backend"
  api "API" shape:hexagon
  db "Database" shape:database
end

# with icon
group contact-center icon:aws-connect,#info
  text:
    Owned by support operations.
  api
end

# styled, no members yet
group agents shape:solid

Attach explanation to the next timeline command. Examples: Notes, Numbered notes.

Syntax:

# basic note
# note: Redis avoids a full Postgres round-trip here.
api -> cache: GET session

# timed note
# note 3s: Stripe responds after fraud checks.
api -> payments: charge card

# manual advance
# note pause: Read this before the next step.
api -> db: SELECT users

Canvas-level messages for scenario transitions, time skips, or major status changes. Example: Overlays.

Syntax:

# overlay: <icon:clock> 5 hours later
# overlay pause: <icon:alert-triangle #warning> Database unreachable

Plain # comments do not render. Special forms # phase:, # note:, and # overlay: create visible timeline content.

# This is a source comment.
# It does not render by itself.

Data objects with identity that travel between components. Declarations are optional; using %key in an edge label creates the artifact automatically. Example: Artifacts.

Syntax:

# declare and use
artifact jwt "JWT Token" icon:key-round
auth -> user: issue %jwt
%jwt: {sub: "user123", exp: 3600}
user -> api: GET /profile %jwt

# instances
%order#123: {status: "paid"}
%order#456: {status: "pending"}
api -> queue: publish %order#123

Clear

Reset component state, artifact state, or everything. Example: Clear.

--clear
--clear api, cache
--clear %jwt

Visibility

Control component visibility. Example: Visibility.

--dim cache
--show cache
--hide legacy
--outline future-service

# apply to all
--dim
--show

Timing

Control playback speed and delays. Example: Timing controls.

--wait 500ms
--wait 2s
--step 750ms
--speed 5
--speed

Autonumber

Add sequential action badges to sends, receives, and state updates. Example: Autonumbering.

--autonumber
--autonumber 10
--autonumber off

Detach and attach

Run blocks in the background. Example: Blocks.

--detach @healthcheck
api -> db: query
--attach @healthcheck

Repeat

Loop a set of commands. Example: Repeat & Speed.

repeat 3
  client -> api: retry
  api -> client: 503
end

*repeat heartbeat
  monitor -> api: GET /health
end

Parallel

Run commands concurrently. Example: Parallel.

parallel
  api -> db: write record
  api -> cache: invalidate
  api -> logger: audit entry
end

Blocks

Reusable named command groups. Invoked with @name. Example: Blocks.

block healthcheck
  api -> db: SELECT 1
  db -> api: OK
end

@healthcheck

*block poll
  monitor -> api: GET /health
end

Hold structured state that can be updated and rendered on components. Example: References.

$state: {
  text: "CLOSED",
  failures: 0
}
breaker: $state
$state.failures++
$state.text: "OPEN"
breaker: $state

For larger diagrams, use the built-in examples from the editor dropdown:

• Basic topology
• Content formats
• Circuit breaker
• Health check
• JWT revocation
• Parallel deployment