ArchTruth User Guide

ArchTruth turns a ServiceNow CMDB into living architecture diagrams: generated from the records, edited as canvas or code, with future state designed as a layer over what exists. The change request and the decision record come out of the diff, and your coding agents can keep everything current through an API. This guide walks through the product in the order you will meet it.

1. Getting started

Sign in. Go to archtruth.app and enter your email; a magic link signs you in and creates your account on first use. There is no password to remember.

Accounts and workspaces. An account is the contract: it groups workspaces, has its own members (owner, admin, member — owners add existing users directly or invite new people by email) and gives owners and admins a decision register and an activity feed across every workspace — open them from My Workspaces. Everything you work on lives in a workspace. You can create as many as you like (one per team or estate is typical). The person who creates a workspace is its owner; owners manage members, billing, data sources, API keys and policies. Other members are editors (change files, layers, decisions, exports) or viewers (read and export images).

Finding your way. Signed in, every public page and the Playground show a My Workspaces button back to your workspace list. Inside a workspace the top bar reads ArchTruth / workspace and a left sidebar carries Overview, Decisions, Audit and Settings; while you edit a file the sidebar shrinks to icons so the canvas keeps its room. The workspace overview shows counts of diagrams, docs and decisions, this month's AI usage, the file list, and the create forms. Search or jump to in the top bar (or Ctrl+K / ⌘K) finds files in the current workspace, sections, and your other workspaces.

Light and dark. ArchTruth follows your system theme. The sun/moon button in the header overrides it — click to cycle system → light → dark; the choice is remembered on that browser.

First run. A new workspace shows a Finish setup banner that opens the first-run page (/app/<workspace>/onboarding): connect ServiceNow, pick one business application and a depth, and open the generated diagram — three steps on one page, each stating what does and does not happen to your instance. The banner disappears once a source is connected and a diagram exists; the page stays reachable by URL.

Playground. /playground is the full editor with a sample diagram and no sign-in. Nothing you do there is saved beyond your browser. It is the fastest way to learn the DSL.

2. Connect ServiceNow and generate a diagram

1. On the workspace page, under Data sources (or on the first-run page), click Connect ServiceNow and enter your instance URL. You are sent to ServiceNow to approve a read-only OAuth grant; ArchTruth never writes to your instance. Tokens are stored in an encrypted vault.
2. Once the source shows connected, use the scope picker: type two or more characters of a Business Application or Service name and choose it from the list.
3. Pick a depth (how many relationship hops to follow from the scope; 2 is a good default) and click Sync & generate. Within about fifteen seconds a diagram opens, grouped by CSDM family, with every node bound to its configuration item.

Each generated node carries a binding such as sn: cmdb_ci_server:c0de12 — the class and sys_id of the record. That binding is how the diagram stays honest: Refresh (in the Data panel) re-reads the records and shows what changed without redrawing anything.

3. The editor: canvas and code

A diagram is one text file in the ArchTruth DSL. The canvas on the right and the code on the left are two views of the same text: drag a box and the layout changes but the DSL does not; type a line and a node appears. Positions are stored separately and never enter the DSL, so diffs only ever show real architectural change.

Layout. The code and the canvas share the window; drag the divider between them (or focus it and use the arrow keys) to resize, double-click it to reset — the split is remembered in your browser.

Canvas controls. Drag nodes to move them; drag from a node's handle to another node to connect; select and press Delete to remove. Without a mouse: click a node, press C, click the target, press C again — a status pill narrates the connection; Esc cancels. Auto-layout re-arranges everything; Add node appends a node to the code and places it.

Node cards. A bound node shows its CMDB class under the label once a record backs it (the DSL kind until then), a criticality dot on the left (red 1, amber 2, green 3, grey 4 — from busines_criticality), and a hover card with the sys_id, class, criticality, owner, support group, environment, status and last update, plus whether the record was in the last sync. The sys_ids toggle in the Edit group swaps every subtitle to the sys_id for screenshots and reviews. Moving a node never changes its sys_id: layout is yours, identity comes from the CMDB.

Saving. Changes save automatically (the footer shows saved / unsaved / saving). Save version opens a small inline prompt for a message and takes an immutable snapshot; Versions → Full history shows who saved each one and the exact lines that changed.

Exports. The Export menu in the toolbar offers SVG, PNG and — when a layer is active — the CR package zip (also available from the Changes panel, section 5). Docs export with Download Markdown.

4. The DSL in five minutes

diagram "Order Management — current" [style: csdm-default]

// Comments start with two slashes and survive every edit.
group app "Order Management" [sn: cmdb_ci_business_app:9f2a1c, icon: business-app] {
  service checkout "Checkout API"   [sn: cmdb_ci_service_auto:1b77aa, owner: "Team Atlas"]
  service orders   "Orders Service" [sn: cmdb_ci_service_auto:5e01bb]
}

group infra "AWS us-east-1" [icon: aws] {
  database orders_db "orders-pg" [sn: cmdb_ci_db_postgresql_instance:aa31cc]
  server   worker_1  "order-worker-01" [sn: cmdb_ci_server:c0de12]
}

app.checkout -> app.orders    : "REST"
app.orders   -> infra.orders_db : "SQL"

Nodes. kind id "Label" [props]. Kinds: service, database, server, queue, cache, app, user, group. The id is how other lines refer to the node; the label is what people see. Props are key: value pairs in square brackets — strings in quotes, numbers bare, lists in [ ]. sn: binds a node to a ServiceNow record; icon: picks an icon; anything else (owner, tier, status, env) is yours to use in rules.

Groups. group id "Label" { … } nests nodes. Refer to a nested node by its path: app.checkout.

Edges. from -> to : "label". Directions: ->, <-, <->, and -- for an undirected link. Two edges between the same nodes need an explicit [id: …] to be told apart.

Rules (conditional formatting). rule name when <condition> [decoration]. Conditions compare node props or the bound ServiceNow record (sn.<field>) with ==, !=, <, <=, >, >=, in [ … ], contains, combined with and, or, not. Functions: lower(), len(), days_since(). Comparisons are case-insensitive for text. Decorations: stroke and fill (tones danger, warn, ok, info, muted, accent, or any colour), opacity (0–1), badge (up to three characters).

rule crit  when sn.busines_criticality == "1 - most critical" [stroke: danger, badge: "!"]
rule stale when days_since(sn.last_discovered) > 30           [opacity: 0.5]
rule prod  when lower(sn.environment) in ["prod", "production"] [badge: "P"]
rule owned when owner contains "atlas"                         [fill: info]

Rules apply the moment you type them. The ServiceNow field name busines_criticality really is spelled that way.

Layers. A layer id "Label" { … } block holds future-state changes: add nodes and edges as usual, and remove base items with ! (!node legacy_db, !app.checkout -> app.orders). The base text is never touched. See section 5.

Diagnostics. The footer counts errors and warnings; hover an underlined line in the code for the message. A diagram with errors keeps rendering from the last good parse.

5. Future state, compare, and the change request package

1. Open the Layers menu in the toolbar (it shows the active layer — Base by default), type a name under New layer and click Create; the canvas switches to it. The same menu switches between Base and any layer. Everything you now add, remove or connect is recorded in the layer block; the current state stays intact underneath.
2. Compare overlays both: ghosted removals, green additions, dashed red edges for removed relations.
3. Changes (n) lists every added, removed and changed component and relation, each with the ServiceNow sys_id behind it.
4. Export CR package downloads a zip: before.png, after.png, changes.csv, changes.json and cr.md. cr.md is laid out like a ServiceNow change form: a header block (short description, risk, impact, configuration items, affected business services, assignment group), the justification citing the decision records linked to the layer, a risk and impact analysis derived from the business criticality of the touched CIs and the services found above them in the synced CMDB, a CI table with class, sys_id, owner, support group and status, an implementation plan in dependency order, a backout plan (the inverse diff, in reverse), and a test-plan checklist. Fields it cannot know — type, category, dates — are marked _fill in_. Elements without an sn: binding are listed as unbound and the risk is reported as Not assessed until they are bound. Every export is also recorded on the workspace's Audit page.

Switch back to Base in the layer selector to see the current state; layers are kept in the same file, so one diagram can carry several candidate futures.

6. Decision records (ADRs)

Decisions in the top bar lists the workspace's architecture decision records: numbered (ADR-0001, …), with a status lifecycle (proposed → accepted → deprecated / superseded) and a supersedes link. Create one with a title; it opens as a document pre-filled with the MADR template (context, options, decision, consequences).

On Team and Enterprise plans (or the Decision Records add-on), an ADR can be linked to a diagram and a layer, so the decision sits next to the change it justifies; Draft with AI writes a first draft from that layer's change set; members can approve or reject with a note; and the Decisions page can export the decision log as CSV (Enterprise). When an Enterprise workspace turns on the policy CR export requires an accepted decision record, the CR package cannot be exported from a layer until an accepted ADR is linked to it.

7. Design documents

A doc is a rich-text page that never goes stale. Type ![[Diagram name]] to embed a live render of a diagram in the workspace — it re-renders whenever the diagram changes. Type [[File name]] for a link to any file; unresolved names show in red so nothing you typed is lost. Markdown shortcuts work (# headings, - lists, code fences). Download Markdown exports the page with embeds and links as ![[…]] and [[…]].

8. Versions, history and the audit trail

Every diagram keeps immutable versions (snapshots you save, plus one for every API write). Full history shows each version with its author — a person's email or the API key that wrote it — and a line diff of the DSL against the previous one. Restore brings back both the text and the layout.

Owners have an Audit page: an append-only trail of every write in the workspace (files, diagrams, layers, decisions, share links, keys, sources, members) naming the person or key behind it, with a redacted diff, plus the ledger of every CR package exported. Hashes and secrets never appear. Account owners and admins also get an Activity feed on the account page — the same trail merged across every workspace in the account, with a workspace column and table filters.

9. Sharing

From a diagram, Share → New link creates a view-only URL with an optional expiry (7, 30 or 90 days, or never). Anyone with the link sees the rendered diagram and can export SVG or PNG — never the DSL, versions or linked records. Revoke kills a link immediately.

10. API keys, REST and MCP

Owners create API keys under Settings → API keys: a name, a scope (read or write), shown once and stored as a hash. Keys authenticate the REST API (/api/v1, OpenAPI 3.1) and the MCP server (/api/mcp), which expose the same operations: list, get, search, render, validate, create, patch with typed operations, replace.

To let Claude Code maintain your diagrams: claude mcp add --transport http archtruth https://archtruth.app/api/mcp --header "Authorization: Bearer <key>". Writes use If-Match with the diagram's revision: if someone edited since the agent read, the write returns 412 and the agent re-reads — two writers, no clobbering. Every write becomes a version attributed to the key. Rate limits are 120 reads and 30 writes per minute per key. Details: /docs/api.

11. Members, plans and billing

Members (Settings, owners): invite by email with a role; people new to ArchTruth get an invitation email, existing users see the workspace on their next sign-in. Change roles inline; remove members; revoke pending invitations. A workspace always keeps at least one owner.

Plans belong to the account (ADR-0002): one subscription covers every workspace in it, a person occupies one seat however many of the account's workspaces they join, and the AI token allowance is shared across the account. Free covers the editor, AI generation and one read-only source. Pro adds unlimited files, data linking and rules, layers and CR packages, REST and MCP. Team adds advanced decision records and review features (the Decision Records add-on for Pro is no longer offered at checkout; existing subscriptions keep it). Enterprise adds SSO, audit export, governance policies and a private connector, under contract. Every member is a seat; Team starts at five. Plans also cap workspaces per account: Free 1, Pro 3, Team 10, Enterprise unlimited.

Deleting a workspace (Settings → Delete, owners): the page lists exactly what will be removed — diagrams, docs, decisions, versions, members, sources and synced records, API keys, share links, CR ledger entries — and asks you to type the workspace slug. A workspace with an active subscription cannot be deleted until it is cancelled under Billing. The audit trail is kept.

AI allowance. Each workspace has a monthly allowance of AI tokens — Free 200,000, Pro 2,000,000, Team 5,000,000, Enterprise unlimited — counting every Generate, Edit and Draft with AI (input and output, including automatic repairs). Syncing from ServiceNow, rules, layers, compare, exports, docs and the API use no AI tokens. Settings shows the meter and, for owners, this month's usage per member; paid workspaces can also set a monthly cap below the allowance (it can never raise it). When the allowance or cap is used, AI actions pause until the 1st of the next month (UTC).

Settings is split into tabs: Members & policies, AI usage, Billing, and API keys.

Billing (Settings → Billing, account owners): Start Pro or Start Team opens Stripe Checkout; Manage billing opens the portal for seats, invoices, payment method and cancellation. Cancelling keeps access to the end of the period. The Pro card offers the Decision Records add-on ($6 / user / month) as a checkbox at checkout — it unlocks the advanced ADR tier (layer links, approvals, AI drafts, CR citations) and rides the same subscription. See the Terms for the refund policy.

12. Keyboard reference

13. Troubleshooting

"Sync & generate" is disabled. Pick a configuration item in the scope picker first.

ServiceNow sign-in fails with 401 access_denied. The OAuth client secret configured for ArchTruth does not match the OAuth record on your instance; re-enter it. A redirect_uri error means the record's redirect URL is not https://archtruth.app/api/connectors/servicenow/callback.

A node does not change when I add a rule. Check the footer for errors, then the Data panel for the field's actual value — rule comparisons are exact (use lower() or in [...] for variants), and sn. fields come from the synced copy, so Refresh after changing the record.

The editor shows "This version is out of date". A new release was deployed while the page was open; reload.

An invitation email never arrived. Ask the owner to check the pending list under Members; invitations expire after 14 days. People who already have an ArchTruth account are added without an email on their next visit to /app.

Export CR package is disabled. Either the layer has no changes yet, or an Enterprise policy requires an accepted decision record linked to that layer — the reason is shown next to the button.

Questions or feedback: mike@mikereams.com.