Revelation

The architecture model format your AI can read, write, and reason about.

---

What it is

Revelation converts a structured JSON model into architecture diagrams across multiple frameworks: C4, ArchiMate, BPMN-Lite, Sequence, ER, and Flowchart. The model lives in a flat JSON file in your repo — no proprietary format, no login, no data leaves your machine. Because it is plain JSON, any LLM can generate, analyse, or transform a Revelation model without custom tooling.

---

The JSON model

{
  "model": {
    "TITLE": { "value": "Basic Start Model" },
    "AUTHOR": { "value": "Steve White", "readOnly": "true" },
    "MODELTYPE": { "value": "C4", "inputType": "select", "refData": "MODELTYPE" },
    "DESCRIPTION": {
      "value": "Basic starter model demonstrating simple systems and interactions",
      "inputType": "textarea"
    },
    "LAYOUT": { "value": "VerticalFlow", "inputType": "select", "refData": "LAYOUTTYPE" }
  },
  "systems": [
    { "ID": "SYS1", "TEXT": "System 1", "TYPE": "SYSTEM" },
    { "ID": "SYS2", "TEXT": "System 2", "TYPE": "SYSTEM" },
    { "ID": "ACT1", "TEXT": "Actor 1",  "TYPE": "ACTOR" },
    { "ID": "DS1",  "TEXT": "Datastore 1", "TYPE": "DATASTORE" }
  ],
  "interactions": [
    { "ID": "INT1", "FROMID": "SYS1", "TOID": "SYS2", "TEXT": "Order",          "TYPE": "->" },
    { "ID": "INT2", "FROMID": "ACT1", "TOID": "SYS1", "TEXT": "Customer Order", "TYPE": "->" },
    { "ID": "INT3", "FROMID": "SYS1", "TOID": "DS1",  "TEXT": "Data",           "TYPE": "->" }
  ]
}

Drag this file into Revelation and it renders as a C4 diagram instantly.

---

Schema overview

Key	Purpose
model	Diagram metadata: title, author, type, description, layout
systems	Nodes — actors, systems, datastores, processes, entities
interactions	Edges — directed or bidirectional relationships between nodes
layouts	Optional layout position overrides

---

Supported diagram types

• C4 — Context, Container, Component views
• ARCHIMATE — Enterprise architecture layers (Business, Application, Technology)
• BPMN_LITE — Business process flows with swimlanes, gateways, and events
• SEQUENCE_DIAGRAM — Message sequence and interaction diagrams
• ERD — Entity relationship diagrams
• FLOWCHART — General-purpose flow diagrams

---

Quick start

1. Copy Reference/Models/Getting Started/basic.json from this repo
2. Edit the JSON to describe your system
3. Open https://revelationcore.com/app/index.html and drag the file in

---

AI integration

Because the model is flat JSON, any LLM can generate valid Revelation models. See the schema/ folder for the formal JSON Schema and copy-paste AI prompts in schema/README.md.

---

Reference models

This repository contains 47+ curated reference models in Reference/Models/, covering sector models (Education, Retail, Manufacturing, Travel, Legal), diagram type examples (ArchiMate, BPMN-Lite, Sequence, ER, Flowchart), and layout demonstrations. Community-contributed models live in models/.

---

Contributing

To contribute a reference model or report an issue, see CONTRIBUTING.md.

---

License

Apache 2.0 — see LICENSE.