archspec turns one YAML file, the spec, into architecture and sequence diagrams, a security review of every connection, data mappings and implementation briefs, and checks it for mistakes the way a compiler checks code. Everything runs in your browser; nothing you type is uploaded.

Every example on this page was drawn by the archspec engine from the spec next to it. Paste one into the playground to change it.

#The app

The spec editor is on the left and the views it produces are on the right. Everything updates as you type. Click something in a view to see where it is written in the spec, and click a line of the spec to see it in the view (see Moving between levels). Need more room? « Hide in the Spec header hides the code on every tab until you click Show spec ».

Pick an Example at the top to see a complete spec, or click New to start from scratch: you get a blank spec on the Architecture tab with the form for your first component open. If the current spec has unsaved changes, New asks first, and Undo brings it back.

#The examples

Each example shows a different architecture style. Open one from Example and look at its Architecture, Sequence and Boundaries tabs.

#Start with the business flow

You don't need protocols and tables to start. Describe the business first: who uses which systems, and what passes between them. Then open each system and design what is inside it.

components:
  customer: { kind: person, title: Customer }
  website:  { kind: system, title: eCommerce Website }
  orders:   { kind: system, title: Order Processing Engine }
  warehouse: { kind: external, title: Warehouse Partner }
connections:
  customer_to_website: { from: customer, to: website, label: places orders }
  website_to_orders: { from: website, to: orders, label: submits orders }
  orders_to_warehouse: { from: orders, to: warehouse, label: sends picking lists }

Links are connections without a type. They say what the relationship is, in business terms, and the technical rules skip them. Once you add typed connections between the components inside, the link shows how underneath its label, such as via gRPC. A link with nothing designed under it yet is drawn dash-dotted, labelled not designed yet, and reported as DES001 (info), so you can see what is still to do.

Drilling down. On the Architecture tab, a box with more inside it is drawn as a stack and has an open › button. Click it to look inside: you see the components of that system, with whatever they talk to outside it at the sides. Lines between boxes roll up: a line between two systems stands for every connection between their components. Inside a component you see its endpoints (one per call it receives), message handlers and scheduled jobs, taken from the flow. The bar above the diagram shows where you are; click a level in it, or ↑ Up a level, to go back.

The Sequence tab follows the same level. At the top it shows what happens between people and systems, and steps that stay inside one system collapse into one line, such as S10–S12: 3 steps inside Order Processing Engine. Click that line to open the system.

The sequence follows the architecture. Connections and links that no flow step uses yet appear on the Sequence tab straight away as dashed draft messages, in call order from the callers. Click a draft connection to add it to the flow as a step (the kind follows from the ends: a call, a transaction, a publish or a consume), or Add n drafts to the flow to add them all. Draft links stay drafts until you design them with connections inside the systems.

Specs without systems keep working as before: the Architecture tab shows every component.

#Spec file basics

A spec is a YAML file, usually named something.spec.yaml. These keys come first:

archspec: 1                         # format version
spec: order-placed                  # lowercase name, used for file names and titles
summary: Client places an order; fulfillment creates a shipment.
imports:                            # platform catalogs (see "Platform catalogs")
  - ../platform/connection-types.yaml
  - ../platform/vendors.yaml
  - ../platform/data-labels.yaml

Then come the sections, all optional except components and flow:

In the examples on this page the header lines are left out for brevity; the app adds them.

#Components

Each component has an id (lowercase, - and _ allowed) and a kind. The kind sets the shape in the diagrams.

components:
  web:       { kind: external, title: Web App }
  api:       { kind: service,  title: Orders API, owns: [orders_db] }
  orders_db: { kind: database, title: Orders DB, engine: postgres }
connections:
  web_to_api: { from: web, to: api, type: https-rest, auth: oauth2-jwt, edgeProtection: WAF, timeout: 3s, retryPolicy: none }
  api_to_orders_db: { from: api, to: orders_db, type: postgres, auth: iam-db-auth, statementTimeout: 1s, connectionPool: 10 }

Other component keys:

#Zones and trust boundaries

Give components a zone. A connection between two zones crosses a trust boundary: archspec works the boundary out for you (dmz->private), draws zones as shaded bands, and holds boundary crossings to stricter rules.

• Connections that cross a boundary must authenticate (rule P2).
• Connections from an external party are public endpoints and must say how they are protected at the edge with edgeProtection (rule NET003).
• Connections to an external party are outbound vendor calls; the target needs an approved vendor (rule NET002).

components:
  web:      { kind: external, title: Web App, zone: internet }
  api:      { kind: service,  title: Profile API, owns: [db], zone: dmz }
  db:       { kind: database, title: Profile DB, zone: private }
  mail:     { kind: external, title: Email Provider, vendor: relay-mail, zone: internet }
connections:
  web_to_api: { from: web, to: api, type: https-rest, auth: oauth2-jwt, edgeProtection: "WAF, 20 req/s per user", timeout: 3s, retryPolicy: none }
  api_to_db: { from: api, to: db, type: postgres, auth: iam-db-auth, statementTimeout: 1s, connectionPool: 10 }
  api_to_mail: { from: api, to: mail, type: https-rest, auth: api-key, timeout: 5s, retryPolicy: provider dedupes }

Callers are drawn on the left and third parties on the right, so traffic reads left to right. You can also write boundary: internet->dmz yourself; it must match the zones (rule NET004).

#Connections

Every edge is a connection with an id and a type from the platform catalog. Name it after its ends, <from>_to_<to> (orders-api_to_orders_db), so flow steps read on their own: via: orders-api_to_orders_db. The editor names new connections this way, and renaming a component renames the connection ids made from it. A second connection between the same two components gets _2. Short ids such as C1 work too; diagrams print short ids on the line and leave descriptive ones to the tooltip, since the line already joins the two named boxes. The type sets the protocol, default port, sync or async, encryption and the allowed auth methods, and lists the properties every connection of that type must set.

connections:
  payments-svc_to_card-processor:
    from: payments-svc
    to: card-processor
    type: https-rest
    auth: api-key                  # must be one the type allows (rule P11)
    port: 8443                     # optional: overrides the type's default port
    timeout: 4s                    # durations: 250ms, 4s, 2m
    retryPolicy: idempotency key makes a retry safe
    carries: [ChargeRequest, ChargeResult]   # data types sent over it
    encryption: { atRest: SSE-KMS }          # queues and databases: encryption at rest

Queue consumers also take dlq (the dead-letter queue component) and idempotentConsumer (the table used to skip duplicate deliveries, rule P4).

#Data types

Types describe payloads: requests, responses and events. Type names are PascalCase.

components:
  web: { kind: external, title: Web App, zone: internet }
  api: { kind: service, title: Profile API, zone: dmz }
connections:
  web_to_api: { from: web, to: api, type: https-rest, auth: oauth2-jwt, edgeProtection: WAF, timeout: 3s, retryPolicy: none, carries: [ProfileUpdate, ProfileSaved] }
types:
  ProfileUpdate:
    description: Name and email change
    classification: confidential
    fields:
      userId:  { type: uuid }
      email:   { type: string, pii: true }
      name:    { type: string, labels: [pii], optional: true }
      address: { type: Address }
  Address:
    fields:
      lines:   { type: "string[]" }
      country: { type: string, enum: [GB, US, DE] }
  ProfileSaved:
    description: Confirmation
    fields:
      status: { type: string, const: saved }

Field types: uuid, string, int, number, bool, timestamp, json, another type's name, or a list such as "OrderItem[]" (quote it in YAML).

A type's description appears in the Data column of the security tables.

#Sensitive data labels

Label fields and columns with what kind of data they hold. Labels come from the platform catalog data-labels.yaml:

pii: true is shorthand for labels: [pii]. Labels travel with the data. A connection carrying a type, or a database connection writing a table, gets every label inside it, including labels inside nested types and JSON columns.

• Encryption (rule P1): a connection carrying a label marked "must be encrypted" needs encryption in transit, and at rest when it goes into a queue or database.
• Vendors (rule NET002): each approved vendor lists the labels it may receive (dataAllowed). Sending PCI data to a vendor approved only for PII is an error. What counts as sent comes from the flow: request and publish bodies go to the vendor, respond bodies come back from it. A connection no step uses is checked against its carries.
• Unknown labels are errors (rule DAT004).

Sensitive connections are drawn in orange, and the Data column shows red flags for labels that must be encrypted and blue ones for the rest.

#Tables

Tables are named database.table and belong to the database component before the dot.

tables:
  orders_db.orders:
    description: Orders
    columns:
      id:              { type: uuid, pk: true }
      customer_id:     { type: uuid, pii: true }
      status:          { type: text, enum: [PLACED, CANCELLED] }
      total_cents:     { type: bigint, labels: [financial] }
      idempotency_key: { type: text, unique: true }
      notes:           { type: text, nullable: true }
      created_at:      { type: timestamptz, default: now() }
      payload:         { type: jsonb, schema: OrderPlacedEvent }   # JSON with a known shape

Column types: uuid, text, int, bigint, numeric, bool, timestamptz, jsonb. Columns are NOT NULL unless nullable: true. Every insert must set every NOT NULL column that has no default (rule DAT001).

#Flow (the sequence)

flow is the ordered list of steps that becomes the sequence diagram. Each step has an id (S1, S2, S2a, …), goes over one connection (via), and is exactly one of six kinds:

components:
  web:       { kind: external, title: Web App, zone: internet }
  api:       { kind: service,  title: Orders API, owns: [orders_db], zone: dmz }
  orders_db: { kind: database, title: Orders DB, zone: private }
connections:
  web_to_api: { from: web, to: api, type: https-rest, auth: oauth2-jwt, edgeProtection: WAF, timeout: 3s, retryPolicy: same Idempotency-Key, carries: [CreateOrder, OrderCreated] }
  api_to_orders_db: { from: api, to: orders_db, type: postgres, auth: iam-db-auth, statementTimeout: 1s, connectionPool: 10 }
types:
  CreateOrder:  { fields: { customerId: { type: uuid, pii: true }, sku: { type: string } } }
  OrderCreated: { fields: { orderId: { type: uuid } } }
tables:
  orders_db.orders:
    columns:
      id:          { type: uuid, pk: true }
      customer_id: { type: uuid, pii: true }
      sku:         { type: text }
      status:      { type: text, enum: [PLACED] }
flow:
  - id: S1
    via: web_to_api
    call: POST /orders
    headers: { Idempotency-Key: required }
    request: CreateOrder
  - id: S2
    via: api_to_orders_db
    transaction:
      - insert: orders_db.orders
        as: order
        map:
          id:          $uuid
          customer_id: request.customerId
          sku:         request.sku
          status:      "'PLACED'"
        on_conflict: { id: never happens; ids are generated }
  - id: S3
    via: web_to_api
    respond:
      status: 201
      body:
        build: OrderCreated
        map: { orderId: order.id }

Step details:

• call: call: is the label (POST /orders, payments.Capture), or endpoint: names an endpoint the callee declares (see API contracts). request: is a type name, or a build: block that constructs it from data in scope. headers: declares headers the mappings may use, and path parameters in the label ({sku}) can be read as path.sku. as: renames the request (default request).
• respond: status: and body: (a type or a build: block; leave it out for a response without a body). Add as: reply to make a downstream service's response available to later steps.
• transaction: a list of operations: insert, update, delete or select. Each one names its table (insert: db.table), maps columns (map:, not for select or delete), and may add as: (a name for the row), where:, on_conflict: (what happens on a duplicate key) and when: (a condition, documented, not evaluated). A select reads a row, such as a cache lookup, and its as: name makes the columns available to later mappings.
• poll: poll: db.table, as:, where:, every:.
• publish: body: (a type or build:) and usually from: outbox.payload.
• consume: consume: TypeName, plus on_error: and on_unknown_schema_version: (rule P10). as: renames the message (default message).

Triggers. A request from a caller, a poll and a consume each start a new trigger: a separate execution. The sequence diagram shows each one under its own grey band. Names in scope (request, message, row names) only exist within their trigger, the way a variable only exists inside its function.

#Mapping expressions

map: assigns each target field or column from an expression. The checker verifies that every source exists and that its type fits the target (rules TYP001–TYP004).

build: constructs a whole payload; every non-optional field must be set (rule TYP004):

payload:
  build: OrderPlacedEvent
  map:
    eventId:       outbox.id
    eventType:     "'order.placed'"   # must equal the type's const
    schemaVersion: "1"
    orderId:       order.id
    itemCount:     count(request.items)

#Asynchronous flows

Writing to a database and publishing a message in the same request is a dual write: a crash between the two loses or invents events (rule P8; a transaction that only selects is a read, not a write). Write the event to an outbox table in the same transaction, and let a relay publish it:

components:
  api:          { kind: service,  title: Orders API, owns: [db], zone: private }
  relay:        { kind: worker,   title: Outbox Relay, partOf: api, zone: private }
  db:           { kind: database, title: Orders DB, zone: private }
  events:       { kind: queue,    title: order-events, zone: private }
  events-dlq:   { kind: queue,    title: order-events-dlq, zone: private }
  shipping:     { kind: service,  title: Shipping Worker, owns: [ship_db], zone: private }
  ship_db:      { kind: database, title: Shipping DB, zone: private }
connections:
  relay_to_db: { from: relay, to: db, type: postgres, auth: iam-db-auth, statementTimeout: 2s, connectionPool: 2 }
  relay_to_events: { from: relay, to: events, type: sqs-standard, auth: iam-role, encryption: { atRest: SSE-KMS }, carries: [OrderPlaced] }
  events_to_shipping: { from: events, to: shipping, type: sqs-standard, auth: iam-role, encryption: { atRest: SSE-KMS }, dlq: events-dlq, visibilityTimeout: 30s, idempotentConsumer: ship_db.seen, carries: [OrderPlaced] }
  shipping_to_ship_db: { from: shipping, to: ship_db, type: postgres, auth: secrets-manager, statementTimeout: 2s, connectionPool: 5 }
types:
  OrderPlaced: { fields: { eventId: { type: uuid }, orderId: { type: uuid } } }
tables:
  db.outbox:
    columns:
      id:           { type: uuid, pk: true }
      payload:      { type: jsonb, schema: OrderPlaced }
      published_at: { type: timestamptz, nullable: true }
  ship_db.seen:      { columns: { event_id: { type: uuid, pk: true } } }
  ship_db.shipments: { columns: { id: { type: uuid, pk: true }, order_id: { type: uuid } } }
flow:
  - { id: S1, via: relay_to_db, poll: db.outbox, as: outbox, where: published_at IS NULL, every: 1s }
  - { id: S2, via: relay_to_events, publish: { body: OrderPlaced, from: outbox.payload } }
  - id: S3
    via: relay_to_db
    transaction:
      - { update: db.outbox, where: id = outbox.id, map: { published_at: $now } }
  - { id: S4, via: events_to_shipping, consume: OrderPlaced, on_error: retry then dead-letter queue }
  - id: S5
    via: shipping_to_ship_db
    transaction:
      - { insert: ship_db.seen, map: { event_id: message.eventId }, on_conflict: { event_id: already handled; ack and skip } }
      - { insert: ship_db.shipments, map: { id: $uuid, order_id: message.orderId } }

Queues deliver at least once, so consumers see duplicates. The first write after consume must be an insert into the idempotentConsumer table with on_conflict (rule P4).

#Scenarios and invariants

invariants:
  - at most one shipment per order, even with duplicate delivery

scenarios:
  - name: duplicate delivery
    tags: [duplicate-delivery]      # every consumer needs one of these (rule COV002)
    covers: [S4, S5]                # steps it exercises (rule COV001: every step covered)
    when: the same OrderPlaced arrives twice
    then: [1 shipment, both messages acknowledged]

Scenarios become the acceptance tests in agent briefs.

#Findings and how to fix them

Errors (✗) should be fixed. Warnings (!) are probably mistakes. Info (i) is advisory. Click a finding to jump to its line.

components:
  web:  { kind: external, title: Web App, zone: internet }
  api:  { kind: service,  title: API, zone: dmz }
  data: { kind: database, title: Data, zone: private }
connections:
  web_to_api: { from: web, to: api, type: https-rest, timeout: 3s, retryPolicy: none }
  api_to_data: { from: api, to: data, type: postgres, auth: password, statementTimeout: 1s }

The rule pack lives in platform/policies.yaml; the Platform tab shows the one in use.

#Reviewing findings

Each finding on the Findings tab (and under Findings here in the diagram panel) can be triaged:

Reviews are part of the spec, in a reviews section, so they travel with the file, show up in code review, and the command line and SARIF output report them:

reviews:
  - rule: DES001
    at: connections/order-processing-engine_to_warehouse   # where the finding is
    status: reviewed
    comment: Warehouse integration is designed next quarter.
    by: Dana
    date: 2026-10-20
  - rule: DAT003
    at: types/OrderPlacedEvent
    status: done
    comment: eventType is kept for routing and logs.

at names the item (components/orders-api, connections/client_to_orders-api/timeout, flow/S4/request), using step ids rather than positions, so reordering the flow keeps reviews attached; renaming a component or a step updates them too. When the finding goes away, the review is reported by REV001 so you can remove it. A done finding no longer fails archspec check; a reviewed one still does.

Reviews and exceptions differ: an exception (below) is a policy decision recorded with an ADR and attached to the item itself; a review is day-to-day triage.

#Exceptions (suppressions)

Sometimes a rule doesn't apply, such as a public sign-up page that can't require a login. Record the exception where it applies, with the decision record that approved it:

connections:
  visitor_to_signup-api:
    from: visitor
    to: signup-api
    auth: none
    suppress:
      P2: "public sign-up endpoint; captcha and rate limits at the edge, see ADR-012"

Suppressed findings stay visible (marked ~) but don't count as errors, and the Boundaries tab lists them as exceptions with their ADR. A reason without an ADR- reference is itself a warning (SUP001). suppress works on components, connections, types, tables and steps.

#Moving between levels

The Architecture, Sequence and API tabs share the level: open a system on one and the others show the same place.

Clicking shows the code. Click a box, a line, a step, a type, an endpoint on the API tab or a row of the Connections table, and the spec editor scrolls to where it is written and highlights those lines. Your keyboard stays on the diagram, so Delete and the arrow keys still act on the selection.

Clicking the code shows the picture. Click a line of the spec, or move to it with the arrow keys, and the item it belongs to is selected and brought into view: a component or connection on the Architecture tab (opening the level where it is drawn), a step on the Sequence tab, an endpoint on the API tab, a finding on the Findings tab, a row on the Connections tab. It flashes so you can find it. Typing doesn't move anything; only clicks and arrow keys do.

#API reference

Every box has an API reference on the API tab, worked out from the flow, or from the box's declared contract when it has one (see API contracts). Pick a box in the list on the left (it follows the level you are on).

• Endpoints: one per call the box receives (call: POST /orders), or per endpoint it declares. Each shows who calls it, over which connection, with what auth, timeout and trust boundary; the path and header parameters; the request body schema with sensitivity flags and an example; the responses (from the respond steps); the error responses; and the steps that implement it.
• Message handlers, Publishes and Scheduled jobs: the consume, publish and poll steps, with delivery, dead-letter and dedupe details.
• Calls to other boxes: what this box depends on.

For a system, endpoints called from outside it are listed as public and the rest as internal.

Document an endpoint on its call step. description becomes the summary and errors lists error responses by status code:

flow:
  - id: S1
    via: customer_to_storefront
    call: POST /checkout
    description: Turns the saved cart into an order. Safe to retry with the same Idempotency-Key.
    headers: { Idempotency-Key: required }
    request: CheckoutRequest
    errors: { 404: no saved cart with that id, 409: the Idempotency-Key was used for a different cart }

Give fields a description in types and they appear in the schema tables and the OpenAPI.

Download OpenAPI saves an OpenAPI 3.1 file for the box's HTTP endpoints (gRPC endpoints are in the reference but not in OpenAPI), and Download AsyncAPI an AsyncAPI 3.0 file for the messages it publishes and consumes. Open it in Swagger UI, Postman, Redocly or a code generator. Auth maps to security schemes (oauth2-jwt → bearer JWT, api-key, hmac-signature, mtls-identity → mutual TLS), data labels become x-data-labels, and the callers are listed in x-callers. Copy as Markdown copies the reference for a ticket or a wiki page.

#API contracts

The API tab works out each box's endpoints from the flow. To fix a box's API before the flow is written, or to hold every caller to it, declare it: give the component an api with one entry per endpoint, named the way code would call it.

components:
  game:      { kind: service, title: Game Service, zone: dmz }
  board:
    kind: service
    title: Leaderboard
    zone: private
    apiVersion: 1.0.0                # raise the major number for a breaking change
    api:
      getRank:
        call: GET /v1/scores/{userId}
        description: A player's score and rank this month.
        path: { userId: uuid }
        query: { around: { type: int, optional: true, description: players shown above and below } }
        responses:
          200: Rank                  # a type: the response body
          404: no score this month   # text: a response without a body
connections:
  game_to_board: { from: game, to: board, type: https-rest, auth: oauth2-jwt, timeout: 1s, retryPolicy: safe to retry, carries: [Rank] }
types:
  Rank: { fields: { userId: { type: uuid }, score: { type: int }, rank: { type: int } } }
flow:
  - { id: S1, via: game_to_board, endpoint: getRank }
  - id: S2
    via: game_to_board
    respond:
      status: 200
      body: { build: Rank, map: { userId: path.userId, score: "0", rank: "1" } }

An endpoint has:

A flow step uses an endpoint with endpoint: getRank. Its call label and request come from the contract, and its mappings can read the parameters as path.userId, query.around and headers.Name, typed as declared. A step whose call label equals a declared one is matched too, so existing flows pick up a contract without changes.

Queues and topics declare the messages they carry, with the field used as the key and a schema version:

components:
  order-events:
    kind: queue
    messages:
      OrderPlacedEvent: { key: orderId, version: 1, description: one per placed order }

What is checked:

From the flow to a contract. On the API tab, Declare as contract writes the endpoints a box serves according to the flow into its api, with parameters, request, responses and the errors documented on the steps (which move into the contract). Calls the contract doesn't cover are marked not in contract, with Add to the contract. In the step panel, a call to a box with a contract picks its endpoint from a list.

Versions and breaking changes. Give the component an apiVersion. When you change a contract, the API tab lists the contract changes since you last saved: which are breaking (a removed endpoint or response field, a new required parameter or request field, a changed type, a changed message key) and which are compatible (new endpoints, new optional fields). A breaking change needs a new major apiVersion, or the old contract kept working. In CI, compare the spec with the version on the main branch:

git show main:my.spec.yaml > /tmp/before.spec.yaml
node cli/archspec.mjs diff /tmp/before.spec.yaml my.spec.yaml   # exit code 1 on an unversioned breaking change

Contracts flow into the exports: OpenAPI gets typed path, query and header parameters, every declared response, deprecated and the apiVersion; Download AsyncAPI (AsyncAPI 3.0) on the API tab describes the messages a box publishes and consumes, with their keys and versions.

#Reading the diagrams

Architecture:

• Bands are trust zones. Callers are on the left and third parties on the right. Inside a system or component, the bands on the sides hold what is outside it. Boxes follow the data from left to right, so a worker that polls a table (an outbox relay) sits after whatever writes it.
• Thick blue lines are business links. Stacked boxes have more inside them.
• Solid lines are synchronous calls; dashed lines are asynchronous messages; dotted grey lines are dead-letter routes.
• Orange lines carry data that must be encrypted. The label shows the protocol, port and data labels, plus the connection id when it is a short one such as C1 (descriptive ids are in the tooltip, since the line already joins the two named boxes).
• Inside a system or component, its name and kind are on top of a frame around its contents. Its own connections that no flow step uses yet start from a slim bar on the frame's edge.
• Hover a line for its encryption, auth, boundary and payloads.

Sequence:

• One column per participant, in order of first appearance (while draft messages are shown, in call order from the callers instead).
• Solid arrows are calls and database statements, dotted arrows are responses, and dashed arrows are asynchronous messages. Orange arrows carry sensitive data.
• Grey bands mark a new trigger. Yellow notes show error handling and conflict rules.
• Dashed rounded labels stand for steps inside one box; grey dashed arrows are draft messages from the architecture that no step uses yet.

Both diagrams have a legend, and Fit / − / + controls zoom.

#Editing the diagrams

Both diagrams are editors. Everything you do on them is written into the YAML on the left, keeping your comments, so the spec stays the source of truth. The panel on the right edits whatever is selected and lists the findings for it, so you see straight away what is missing.

Architecture

Sequence

The step panel's mapping editor lists every field or column of the target. As you type, it suggests what is in scope and fits the type: a uuid column is offered message.orderId and $uuid, a column with allowed values is offered those values as literals. A transaction can have several operations; later operations can use rows named by earlier ones.

Everywhere: Delete removes the selection, Ctrl/Cmd+Z undoes, Esc clears the selection, and Hide spec code gives the diagram the full width. On any tab, « Hide in the Spec header does the same for every view; Show spec » on the left edge brings the code back, and so does clicking a finding. Use Fit to see the whole diagram while you drag between distant boxes. Tables are edited in the spec code.

#Security review

• Connections: the ports and protocols matrix. Each row shows direction (inbound, outbound, internal), mode, protocol, port, encryption, auth, trust boundary, timeout, and the data carried with its description and sensitivity flags.
• Boundaries: only the connections that cross zones, grouped by boundary, with edge protection, vendor (and its data agreement) and approved exceptions.

Copy either as Markdown for a review ticket, or as CSV for a spreadsheet.

#Saving, opening and exporting

• New starts a blank spec (asking first if you'd lose unsaved work).
• Your work is kept in this browser automatically between visits.
• Save (Ctrl/Cmd+S) writes a .spec.yaml file. In Chrome and Edge it keeps writing to the same file; other browsers download a copy.
• Open… reads a spec from your computer. You can also drop a file onto the editor.
• Export downloads diagrams as SVG or PNG (at the level you are looking at), the connections matrix as CSV, the security tables and the API reference as Markdown, and the model as Mermaid or LikeC4. OpenAPI and AsyncAPI for one box are on the API tab.

Nothing is uploaded: the app makes no network requests after the page loads.

#Agent briefs

The Agent brief tab cuts the spec down to what one or more steps need: the steps themselves, their connections, payload types, tables, invariants, the rules that apply, and the scenarios that cover them as acceptance tests. Give it to a developer or a coding agent with the instruction to implement those steps; the brief tells them to change the spec rather than work around it.

#Platform catalogs

Specs import shared catalogs, usually owned by a platform or security team:

The web app includes the standard catalogs; the Platform tab shows them.

#Keyboard shortcuts

#Command line

The same engine runs in Node for CI and scripts:

node cli/archspec.mjs check  my.spec.yaml                    # exit code 1 on errors
node cli/archspec.mjs check  my.spec.yaml --format sarif     # code-scanning annotations
node cli/archspec.mjs render my.spec.yaml all --out out      # every view, SVG diagrams, design doc
node cli/archspec.mjs render my.spec.yaml architecture-svg --focus orders-api   # one level down
node cli/archspec.mjs render my.spec.yaml openapi --out out  # OpenAPI 3.1 per box with HTTP endpoints
node cli/archspec.mjs render my.spec.yaml asyncapi --out out # AsyncAPI 3.0 per box that sends or receives messages
node cli/archspec.mjs diff   before.spec.yaml after.spec.yaml # contract changes; exit code 1 if breaking without a new major apiVersion
node cli/archspec.mjs render my.spec.yaml api                # Markdown API reference
node cli/archspec.mjs task   my.spec.yaml S5                 # agent brief for step S5