How to use Radical.Tools

Getting started

When you launch the app for the first time you'll see the Welcome screen. Choose a metamodel — C4, C4 + DDD Domains, or C4 + DDD + Governance — optionally load the sample Fintech Banking Platform model, or import an existing .json file. The app opens into Designer mode with an empty canvas.

The UI has three main zones:

• Left panel — element palette (drag to add) and the full node tree.
• Canvas — the main editing area, powered by React Flow.
• Right panel — properties of the selected element, plus the view/milestone panel and the AI chat.

The toolbar at the top controls layout, undo/redo, and the Designer / Viewer / Presenter mode switch. Designer is the full editing environment; Viewer is a read-only sandbox for navigating views; Presenter drives the fullscreen slide deck. The Radical menu (top-left logo button) gives access to model management, metamodel editor, theme, Smart Fit, AI settings, and the connection-key preference.

Adding elements

There are two ways to add a new node:

1. Drag from the palette — grab any type from the left panel and drop it anywhere on the canvas. The node is created at the drop position.
2. Double-click the canvas background — double-clicking an empty area creates a new System node at that exact position. Rename it immediately in the right panel.

Nesting (parent–child)

Elements can be nested to represent containment (e.g. Containers inside a System). Drop a child element on top of a parent node — the parent highlights to confirm the drop target. You can also change the parent via the Parent field in the properties panel. Nested children can be collapsed/expanded by clicking the triangle icon on the parent node or the toggle in the tree view.

Connecting elements

Relations are created by drag-to-connect:

1. Hold the connection modifier key (default: Alt).
2. Press and hold the mouse button on the source node.
3. Drag to the target node and release.

A preview line is drawn while you drag. The relation is validated against the active metamodel — only allowed source→target type combinations produce a connection.

Click a relation to select it and edit its label, technology, and description in the right panel. The edge label is rendered on the canvas and updates live.

Editing & properties

Click any node or edge to select it. Its properties appear in the right panel:

• Label — the display name shown on the canvas.
• Technology / description — secondary text rendered inside the node.
• Type — change the element type (e.g. Container → Database). The node re-renders with the new shape and colour.
• Parent — reparent the element by picking a different parent from the dropdown.

To delete a selected element press Delete or ⌫ Backspace. A confirmation dialog appears if the node has children or connected relations.

Undo / Redo — every action (add, edit, move, delete, layout) is tracked. Use ⌘Z / Ctrl+Z to undo and ⌘⇧Z / Ctrl+Y to redo.

Views

A view is a filtered window onto the shared model. Every element lives in the model once; views decide which subset is visible. This means you can create a high-level System Context view and a detailed Container view without duplicating any data.

Creating and managing views

1. Switch to Viewer mode (toolbar, top-right).
2. Click + New view in the view list on the right panel, then pick a type — Structure, Flow, Hierarchy, Table, Matrix, or Wiki.
3. Give the view a name (e.g. "System Context", "Payment flow").
4. Use the eye icons in the node tree to include or exclude elements for this view.
5. Each view stores its own layout — rearrange nodes here without affecting other views.

You can change a view's type at any time from the view's settings panel (or the Viz dropdown in the view bar), so the same set of elements can be read as a diagram, a table, or a matrix without rebuilding it.

View types

Structure views

Structure is the default view type. It renders nodes and relations on the canvas and is the best choice for classic C4-style slices: System Context, Containers, Components, or any custom architecture subset.

A structure view has its own filtering and layout, but it still points at the shared model. Move elements or exclude them from one structure view and the underlying nodes remain available to every other view.

Flow views

Set a view's type to Flow to add sequence numbers to relations. Then choose the sequence to visualise in the view properties panel. Each matching edge gets a step number (1, 2, 3…) on the canvas.

In presentation mode, flow views replay the sequence one step at a time — ideal for showing user journeys, request lifecycles, integration hand-offs, or incident narratives.

Hierarchy views

Set a view's type to Hierarchy to render the same model as a treemap instead of a node-link graph. Parent elements become nested tiles; child elements are packed inside them.

• Click a tile with children to drill into it.
• Use breadcrumbs or the Up button to zoom back out.
• Choose whether size is based on leaves, uniform sizing, or relation count.
• Limit visible depth to keep dense trees readable, then expand specific branches inline.

Hierarchy views are useful when containment matters more than edge routing: domains, subdomains, platform areas, team ownership maps, or any nested architecture where you want to understand "what lives inside what" first.

Table views

Set a view's type to Table to work with the model as an editable spreadsheet instead of a diagram. Each row is a node; click any cell to edit its name, description, technology, or type inline. Drag an element type from the palette onto a row to add a child, or drag an existing node to reparent it.

The table has four tabs:

• All Nodes — every element as an indented containment tree.
• ADRs — Architecture Decision Records with status, context, decision, consequences, and alternatives columns.
• Fitness Functions — fitness functions with category, automation, trigger, status, and threshold columns.
• Relations — every relation with its source, type, target, label, and technology.

The ADR and Fitness Function tabs require the C4 + DDD + Governance metamodel (see below). The bundled sample model uses it, so you can explore these tabs right away.

Matrix views

Set a view's type to Matrix to render a Dependency Structure Matrix (DSM): the elements appear on both the rows and the columns, and a coloured dot marks every place where a row → column relation exists. The colour follows the relation type.

• Hover a cell to highlight its row and column axes.
• Click an empty cell to create a relation (subject to metamodel rules).
• Click a marked cell to select the relation; click it again to remove it.
• When a pair has several relations, a count badge appears — click to pick one from a popup.

Matrix views are collapse-aware: relations roll up to the nearest visible ancestor, so a collapsed container shows the aggregated dependencies of everything inside it. In Viewer and Presenter modes the matrix is read-only.

Wiki views

Set a view's type to Wiki to browse and edit the model as readable, document-style pages. Each element gets its own page with a large title, a lead paragraph, an infobox of key facts, children cards, and a full relationship list — all editable inline with click-to-edit.

• A navigation tree on the left lets you jump to any element; use the filter box to search by name.
• Properties are rendered dynamically from the active metamodel, so ADRs show status, context, decision, consequences and alternatives, while fitness functions show category, automation level, trigger, and threshold.
• Click any text, badge, or dropdown to edit in place — changes are written to the shared model immediately.
• The wiki respects the view's node visibility filter: toggle elements on or off in the right panel's node tree to control what appears.

Wiki views are ideal for onboarding new team members, reviewing governance artefacts (ADRs, fitness functions), or simply reading the architecture as structured documentation rather than a diagram.

View layout mode

Structure and flow views can independently use Auto (Smart Layout) or Tree layout. Switch via the view's settings panel. In tree mode the Smart Layout button changes to Tree Layout. Hierarchy, Table, Matrix and Wiki views don't use canvas layout — they expose their own controls (depth and sizing, spreadsheet tabs, DSM cells, or document navigation respectively).

Milestones

A milestone is a named snapshot of the entire model state — nodes, relations, views, and layout positions.

Creating a milestone

1. Click the camera icon in the toolbar (or open the milestones panel in the right panel).
2. Enter a name (e.g. "v1 — initial draft", "After sprint 3") and an optional date.
3. Click Save milestone.

Browsing and restoring

All milestones are listed in the right panel with their names, dates, and node/relation counts. Click any milestone to preview it. Click Restore to revert the live model to that snapshot (a new undo entry is created, so you can undo the restore).

Layout engines

Radical.Tools ships three layout engines, each with a different trade-off:

Smart Fit

Enable Smart Fit (Radical menu → View → Smart Fit) to automatically zoom and pan the viewport to fit all visible nodes after every layout run or model change.

Fit All

The Fit All button in the toolbar instantly fits all visible nodes into the current viewport without triggering a re-layout.

Presentation mode

Presentation mode turns your views into a fullscreen slide deck.

1. Switch to Viewer mode.
2. Drag views into the desired order in the slide deck at the bottom of the screen.
3. Click Present or press F5 to go fullscreen.
4. Navigate between slides with the on-screen arrow buttons or keyboard.
5. Flow views replay their sequence steps one at a time — each press of the forward arrow reveals the next numbered relation.
6. Press Esc or F5 again to exit presentation mode.

AI integration

The built-in AI assistant can answer questions about the model, detect gaps, and apply natural-language changes as structured patches.

Opening the AI chat

Press ⌘P / Ctrl+P to focus the quick-search bar. Type > (right angle bracket) to switch into AI mode. The bar expands into a chat thread.

Example prompts

• "Add a Redis cache container between the API Gateway and the User Service"
• "What components talk directly to the database?"
• "Rename Payment Service to Payment Processor and update all its relations"
• "List all containers that have no outgoing relations"

Destructive changes are shown as a diff before being applied. Press ⌘↵ / Ctrl+Enter to send a message to the AI without applying any pending patch.

Configuring providers

Go to Radical menu → AI → AI providers… to configure your preferred LLM. Supported providers:

• Ollama — local models, no API key required.
• OpenAI — GPT-4o and other OpenAI models.
• Anthropic Claude — Claude 3 / Claude 4 family.
• Google Gemini — Gemini 1.5 / 2.0 models.

Metamodel editor

The metamodel defines which element types and relation types exist in your diagram, along with their colours, icons, and allowed connections.

Open it via Radical menu → Schema → Metamodel editor… The canvas is replaced by the metamodel editor. Changes take effect immediately — new types appear in the palette and existing nodes re-render with any updated colours.

Built-in metamodels

Three presets ship built-in. Choose one on the Welcome screen (or via Radical menu → Models → New model):

• C4 — Person, Software System, Container, Component, Database, Web App, Queue.
• C4 + DDD Domains — adds a strategic Domain container that nests recursively (Core / Supporting / Generic) above the technical model, plus DDD relations such as Realises, Depends on, and Partnership.
• C4 + DDD + Governance — adds two governance node types and links them to architecture elements (see below).

Governance: ADRs & Fitness Functions

The governance metamodel makes architectural intent part of the model itself:

• ADR — an Architecture Decision Record (Nygard / MADR style) with status, date, context, decision, consequences, and alternatives considered.
• Fitness Function — an objective, often automated check from Building Evolutionary Architectures, with category, automated, trigger, threshold, and status.

Three governance relations connect them to the architecture: Constrains (an ADR or Fitness Function → any element), Supersedes (a newer ADR → an older one), and Implements (a Fitness Function → the ADR it verifies). Manage these records most comfortably in a Table view, on its ADRs and Fitness Functions tabs. The bundled sample model uses this metamodel.

You can add custom node types (with a custom label, icon path, and colour) or remove types that don't apply to your architecture. Relation types let you define which source and target combinations are valid.

Files & documents

Radical.Tools stores models as plain JSON files. You can diff them in git, edit them in a text editor, and automate transformations with any script.

Document manager

Open Radical menu → Models → Manage models… to create, rename, duplicate, or delete models. Each model is either:

• LOCAL — stored in browser localStorage (survives page reloads, tied to the browser profile).
• FILE — an explicit .json file opened from the filesystem via the Electron file dialog.

Import / Export

In the document manager, use Export to save the active model as a .json file, or Import to load one. In the desktop (Electron) app this opens a native file dialog; in the browser it uses a file input / download.

Keyboard shortcuts