The Revelation Quick Guide

Revelation is a diagrams-as-code Enterprise Architecture tool that automatically generates rich, interactive architecture diagrams. Instead of relying solely on graphical drag-and-drop interfaces (common in many EA tools), Revelation generates diagrams automatically from structured text files like Excel workbooks or JSON.

How Revelation Works

Each diagram is built from:

Systems – typically your applications, capabilities, or components, and
Interactions – the flows or relationships between those systems.

Each system and interaction has a unique ID along with TYPE and a TEXT properties. In addition, Interactions detail the system ID data flows from and to. These are captured using the FROMID and TOID fields, which indicate the direction of the interaction. Finally there's optional model meta data. All other properties are user-defined. Take a look at the example files to get a feel for the structure.

Basic – Excel, JSON
Advanced – Excel, JSON

But Revelation is more than just application and dataflow modeling - it can represent any structure with connected elements, from org charts to entity relationships to capability models.

Getting Started

The quickest way to explore Revelation is through the Revelation Launchpad. Load a sample model, experiment with its views and layouts, then use the File > Save menu to export a copy as an Excel workbook and start customizing.

Views: Different Ways to See Your Model

Accessed via the View dropdown menu, views allow you to explore your data from different perspectives:

Architecture View – The default view, displaying all selected systems and interactions. Example
Capability View – Best for hierarchical data. Collapse/expand nodes; only selected top-level nodes appear initially. Recommended for Capability models and Organisation charts. Example
Transition View – Showcases your digital roadmap, dynamically generating a sequence of views in the View dropdown menu that highlight changes from start to end state. Example. To find out more read the Documenting Digital Roadmaps blog article.

Layouts: How Diagrams Are Arranged

Found under the Layout dropdown, layouts let you control the diagram’s structure:

Horizontal Flow – Draws diagrams left to right.
Vertical Flow – Draws diagrams top to bottom.
Organic – A freeform layout. Drag nodes to reposition, but note that positions reset on refresh.
Centered Rectangle – Focuses on one system, surrounding it with other selected systems. Try dragging a system to the center to refocus the layout.
System Grid – Organizes systems in a grid, optionally grouped by a chosen property.

Tabs: Model, Systems, and Interactions

These tabs let you directly edit the model’s data tables. You can select, filter, sort, and perform actions on rows:

Model – Shows metadata such as title, layout, and view settings.
Systems and Interactions – Provide editable tables with checkboxes to include/exclude rows from the diagram.

Use the Add, Edit, Delete, Copy, and Word Wrap toolbar buttons to make changes to the data.

The master select checkbox at the top allows you to select/unselect all visible items at once.

The Related Checkbox

When Related is checked, Revelation includes all systems that are connected by an interaction to a selected system—even if those related systems aren't selected themselves. Uncheck it to isolate your diagram to just the explicitly selected items.

Fit, Locate, and Zoom Tools

Use these controls to navigate your diagram:

Fit – Automatically resizes the diagram to fit your screen.
Locate – Centers the view on your currently highlighted system or interaction.
Zoom In and Zoom Out – Adjust the zoom level.

Saving and Opening Models

To open a model, use File > Open, choose Excel or JSON format, and click Choose File.
To save a model, use File > Save, select your format, enter a name, and download it to your device.

Exporting Diagrams

Diagrams can be exported for use in documentation or editing:

SVG – Great for documents and presentations.
draw.io – Open and edit with diagrams.net.

Go to File > Export, choose a filetype, and download.

Settings Menu

The Settings dropdown gives you fine-tuned control over your diagram:

Color Map – Apply colors based on a chosen property. Select a Property, choose a Palette, and Enable the color map.
Centered System – Choose the focal system for the Centered Rectangle layout. Or, drag a system to the center manually.
Group by Property – Used with System Grid layout to organize systems into groups.

Reference Dropdown

Use the Reference dropdown to access:

Reference Models – Ready-made examples to explore.
AI Prompts – Kickstart your modeling with curated text prompts.

Get Started

If you got this far you're ready to go! Jump to the Revelation Launchpad and see your architecture come to life!