[ { "slug": "quickstart", "title": "Explore a working architecture", "summary": "Open the demo, drill into a level, and follow a runtime flow.", "prerequisites": "A current browser. No account required.", "outcome": "You can explain the example's components and one connection.", "permission": "Free local use; demo edits are not server publications.", "steps": [ "Open the example on a desktop browser at least 960 pixels wide. Its separate browser draft preserves your main work.", "Select an object to open its inspector. Double-click an object marked with an arrow to open its level.", "Use the breadcrumb to return to the parent view, and Fit to frame it.", "Select a connection to inspect its label and direction. Pause motion if you prefer static flows.", "Choose Save for storage, checkpoints and backup options." ], "reference": "/guide#quick-start", "example": "/app?diagram=demo", "caution": "Do not treat a successful demo visit as proof that account or organization workflows are enabled." }, { "slug": "first-diagram", "title": "Create your first diagram", "summary": "Open a small working model, edit it visually, and keep a portable backup.", "prerequisites": "A browser and a backup export of any current work.", "outcome": "An editable request-path diagram and a portable backup.", "permission": "No account required for local editing and export.", "steps": [ "Open the example below on a desktop browser. It uses a separate browser draft; your main draft stays at /app.", "Select the API object and change Name in the inspector. Click outside the field to finish.", "Choose Add to create a shape, or Browse cloud & technology icons to choose a recognizable icon.", "Choose Connect, click a source object, then a different destination. Select the connection to name it.", "Choose Save → Download JSON backup. For Markdown or YAML, choose Export & view → Edit source & export, select Format, then Download source.", "To use the source below instead, choose Export & view → Import model, select Markdown, paste it, and choose Import as new draft." ], "reference": "/guide#editor", "example": "/app?example=api-database", "fixture": true, "caution": "Local storage is tied to this browser and site. Export important work before clearing browser data." }, { "slug": "hierarchy", "title": "Navigate hierarchy and shared views", "summary": "Distinguish containment from a named view and return to the parent level.", "prerequisites": "A diagram with a container, such as the worked demo.", "outcome": "You can open and leave a level without changing containment.", "permission": "Local editing is free. Server changes require write access.", "steps": [ "Open the demo and select a container.", "Open its deeper level. Without a custom view, this level follows its contained children.", "Use Back or the breadcrumb to return to the previous level.", "Choose Pages & views to create a named page or architecture view with its own scope and placement.", "Use Open level in the inspector to inspect a C4 object’s detail level. Use the breadcrumb to return; export a backup before restructuring views." ], "reference": "/guide#levels", "example": "/app?diagram=demo", "caution": "A shared view within a diagram is not a workspace-wide reusable entity. Those are different capabilities." }, { "slug": "flows", "title": "Explain a runtime flow", "summary": "Connect two services and inspect direction, speed and labels.", "prerequisites": "Two nodes in an editable diagram; the example below supplies both.", "outcome": "One labeled relationship whose direction you can explain.", "permission": "Local editing is free; published updates require write access.", "steps": [ "Open the API and database example in the desktop editor.", "Select the API-to-database connection to inspect its label, direction and appearance.", "Choose Connect, click a source object and then a different destination to add a relationship.", "Use the flow controls to author a named flow when you want to present a sequence; Present plays it without authoring tools.", "Choose Export & view → Edit source & export and inspect the flows array or Flows section." ], "reference": "/guide#markdown", "example": "/app?example=api-database", "fixture": true, "caution": "Reduced-motion preferences can make flows static. Direction and labels remain useful without animation." }, { "slug": "save-and-recover", "title": "Save, sync and recover work", "summary": "Distinguish browser autosave, account sync, checkpoints and portable backups.", "prerequisites": "A local diagram. An active signed-in account is needed for publishing.", "outcome": "A clear storage location, portable backup and recoverable checkpoint.", "permission": "Local saving needs no account. Account saving requires an active account and write access.", "steps": [ "Choose Save to see the current save status and the available storage options. Local drafts autosave only in this browser.", "Choose Diagrams → On this browser to open earlier named drafts or download their JSON backups. New diagrams and imports keep your earlier drafts.", "Choose Download JSON backup to keep an editable copy outside this browser.", "Choose Save to account. If signed out, use Sign in to save this draft; you return to Diagrams with your draft preserved.", "Choose the intended owner and Save to account. Reopened writable account diagrams sync edits; wait for All changes synced.", "Choose Save → Checkpoints → Create checkpoint to name a recovery point. Local checkpoints stay in this browser; account checkpoints belong to the saved diagram.", "Use Review restore to inspect checkpoint differences before restoring. Recover draft in the diagram explorer can recover a previous local draft. Import model can open an exported backup as a new local draft.", "To remove a browser draft, open a different draft first, then choose Move to Recently deleted. Restore it from Recently deleted; browser data is never automatically evicted by Flowboard." ], "reference": "/guide#publishing", "example": "/app", "fixture": true, "caution": "Offline or failed sync is not a successful account save. Keep an export before clearing browser data. Checkpoint retention for account diagrams depends on workspace policy. Only one tab edits a browser draft at a time. A second tab is read-only: close the first and choose Reload latest and enable editing, or Create separate copy. Local coordination requires a secure-context browser with Web Locks support." }, { "slug": "sharing", "title": "Share a diagram for review", "summary": "Publish privately, choose public or email access, and verify the recipient view.", "prerequisites": "A signed-in owner and a successfully published diagram.", "outcome": "An intended reviewer can view the diagram with the access you chose.", "permission": "Personal owners can manage public and email viewing access. Organization policy can restrict sharing.", "steps": [ "Save an example to your account using Save → Save to account.", "Open Diagrams and the saved diagram’s sharing controls.", "Choose private/email access or public visibility deliberately; public access makes the URL readable by anyone.", "Add an intended email recipient for private viewing; the recipient must sign in with that email.", "Save access and verify the diagram link in an authorized recipient session. Revoke access by removing the address or public visibility." ], "reference": "/guide#publishing", "example": "/app", "fixture": true, "caution": "Email sharing grants view access; do not assume it sends an invitation email or gives editing rights." }, { "slug": "workspaces-and-roles", "title": "Understand workspace access", "summary": "Identify personal versus organization ownership and the role needed for a task.", "prerequisites": "A signed-in account; an existing workspace for membership tasks.", "outcome": "You know when to ask an organization owner for access.", "permission": "Free personal accounts can start Team setup. Team billing and Enterprise terms are separate from sign-in.", "steps": [ "Open Account and billing from Diagrams or your account link.", "For a new Team, follow Get started with Team from Pricing, sign in, then choose the workspace, seats and billing cadence. Payment is confirmed separately at checkout.", "For an existing workspace, inspect your membership and role before saving a diagram under that owner.", "Viewers read, commenters review, and editors can change authorized workspace diagrams. Owners and admins manage membership and policies.", "Use existing company SSO when supplied by an administrator. Validate organization identity and governance separately before enforcing them." ], "reference": "/guide#organizations", "example": "/profile?plan=team", "caution": "Workspace access never follows merely from GitHub organization membership. Enterprise deployment and commercial requirements need explicit configuration and agreement." }, { "slug": "import-export", "title": "Round-trip a portable model", "summary": "Import Markdown, export JSON, and inspect the same nodes and flows.", "prerequisites": "A browser and a backup of existing work.", "outcome": "Two nodes and one flow survive a portable export and re-import.", "permission": "Local import/export needs no account.", "steps": [ "Choose Export & view → Import model. Select Source format, paste the example, and choose Import as new draft; or choose a supported file.", "Import creates a local draft without server identity and keeps the previous draft as a recovery copy.", "Choose Export & view → Edit source & export, select JSON, and Download source.", "Import the exported JSON as a new draft and verify the same node IDs and flows.", "Use Edit source & export → Apply changes only when you want to update the current diagram in one undoable action. For account diagrams, applied edits sync to that same saved diagram." ], "reference": "/guide#formats", "example": "/app", "fixture": true, "caution": "GIF is a presentation export, not an editable model import. Use Markdown, JSON or YAML for round trips." }, { "slug": "templates", "title": "Start from a template safely", "summary": "Choose a gallery example or insert a reusable pattern without confusing the two.", "prerequisites": "A desktop browser and a draft you want to keep.", "outcome": "An editable example draft or an inserted reusable pattern.", "permission": "Template download and local editing are free.", "steps": [ "Open Templates in the editor.", "Under Start a separate architecture example, choose a preview. It opens its own browser draft; return to your main draft using My browser draft or /app.", "To insert objects into the current page instead, choose Approval process or Service & data flow under Insert into this page. Undo removes that insertion.", "Select objects and connections, give the selection a name, and Save selected objects to reuse it in this browser. Export that selection to transfer it elsewhere.", "Use New diagram → Architecture examples for the same gallery catalog, or choose a blank diagram." ], "reference": "/guide#formats", "example": "/gallery", "caution": "Examples describe systems; they are not reviewed deployment designs. Insertions and creating a separate example draft are different operations." }, { "slug": "agent-connection", "title": "Connect an agent with a personal key", "summary": "Create a key, connect to MCP, discover shapes, and validate a small model.", "prerequisites": "An active account and an MCP client that supports authenticated HTTP servers.", "outcome": "Your agent can discover shapes and work with an authorized diagram.", "permission": "Personal keys inherit their owner's access. A key does not bypass organization permissions.", "steps": [ "Open MCP setup and sign in. You return to /mcp to manage personal keys. Store a new key privately; it is shown once.", "Configure a compatible client with the Streamable HTTP endpoint and a Bearer header using its private secret mechanism.", "Use Copy verification prompt to ask the connected agent to discover tools and call list_diagrams without modifying data. An empty list is a successful connection.", "Give your agent an existing diagram link, or ask it to create one model, retain the ID and use get_diagram to verify its content. Discover exact shapes through list_shapes.", "Open the returned /app?diagram=ID link in the desktop editor. Reuse that same ID for patch_diagram and subsequent checks; do not create another diagram for every edit." ], "reference": "/guide#mcp", "example": "/mcp", "fixture": true, "caution": "Do not paste keys into diagrams, support messages or public source. Client configuration syntax differs; use your client's documented secret mechanism." }, { "slug": "troubleshooting", "title": "Troubleshoot an import or missing flow", "summary": "Check identifiers, endpoints and access before retrying.", "prerequisites": "The source or diagram that failed, with a backup copy.", "outcome": "You can isolate a source problem from an account or service problem.", "permission": "Local checks require no account. Publishing requires an active account.", "steps": [ "Check that you are using a desktop browser with a window at least 960 pixels wide.", "Choose Export & view → Import model and import the small example below to isolate a source problem.", "Check IDs are unique and valid, and flow endpoints refer to different existing objects.", "Use Fit and the appropriate breadcrumb or view to locate a relationship.", "For sync or access failures, keep a JSON backup, check sign-in and permissions, and report the exact error through Support. For MCP, verify read access with list_diagrams first." ], "reference": "/guide#troubleshooting", "example": "/app", "fixture": true, "caution": "Retrying a failed request is not proof it succeeded. Verify the server copy before discarding local work." }, { "slug": "shortcuts-accessibility", "title": "Navigate with keyboard and reduced motion", "summary": "Focus nodes, open levels and use editing shortcuts without relying on animation.", "prerequisites": "A keyboard and the demo or an editable diagram.", "outcome": "You can select a node, open a level and return using keyboard controls.", "permission": "Viewing and local drafting require no account.", "steps": [ "Open Inspector and use Tab to reach objects in In this view. Select an object to inspect its details.", "Use Open level for nested content and the breadcrumb to return.", "Use A to add an object, Ctrl/Command+K to find in the diagram, and Escape to cancel. The ? button lists current shortcuts.", "Use Ctrl/Command+S for Save options. Delete removes the selection and Undo restores a recent edit.", "Pause motion or use the operating system’s reduced-motion preference; labels and arrows still explain direction." ], "reference": "/guide#editor", "example": "/app?diagram=demo", "caution": "The full editor requires a desktop keyboard and pointer. Mobile editing/viewing is unsupported. Shortcuts do not act while typing in fields." } ]