Scapius vs. Diagramming Tools (PlantUML, Structurizr, Mermaid)

Developers and engineers have embraced Diagrams as Code tools like PlantUML, Mermaid.js, and Structurizr (which formalized the C4 model as code). Storing diagrams in text files alongside code revolutionized documentation by making graphics version-controllable and diffable in Git.

However, as systems grow into true enterprise portfolios, drawing standalone diagrams in code reveals fundamental limitations.

Here is how Architecture as Code (Scapius) differs from Diagram as Code (PlantUML, Mermaid).

---

At a Glance

Evaluation Dimension	Scapius (Architecture as Code)	Diagram-as-Code (PlantUML, Mermaid)	C4 Model as Code (Structurizr)
Core Concept	Single semantic architecture model	Isolated graphic text drawings	Software container model
Scope of Coverage	Full Enterprise (ArchiMate 3.2 + Security)	Pure visual shapes & connectors	Software containers & components (C4)
Data Consistency	Change entity once; all views update	Manually update every .puml / .mmd file	Views update from C4 workspace
Semantic Validation	Compiler enforces legal relationships	None (connect any shape to any shape)	Basic C4 relationship validation
Layout Behavior	Deterministic layout with manual adjustments	Auto-layout resets unexpectedly on edits	Auto-layout with manual layout script
Security & Governance	Native STRIDE threats, controls & heatmaps	None	Limited
Editor Intelligence	Full VS Code LSP (diagnostics, autocomplete)	Syntax highlighting	VS Code extensions / CLI

---

1. Single Model vs. 50 Separate Pictures

Diagrams as Code (PlantUML, Mermaid)

In PlantUML or Mermaid, each diagram is an independent file containing its own node declarations and connections:

' File: payments-context.puml
[Payment API] --> [Payment DB] : writes

' File: payments-flow.puml
[Payment API] -> [Kafka] : publishes
[Kafka] -> [Ledger] : consumes

• The duplicate definition problem: If Payment API changes its name, owner, or tier, you must search and replace across dozens of .puml files.
• Inconsistent states: Inevitably, some diagrams are updated while others are forgotten, leading back to diagram drift.

Scapius

In Scapius, you define each entity and relationship exactly once in your architecture model:

system payment_hub "Payment Gateway" {
    app payment_api "Payment API" {
        writes transaction_db "Posts ledger entries"
        flows_to payment_stream "Publishes events"
    }
}

You then declare views that filter the model:

view landscape core_payments "Core Payment Topology" {
    include app where system == "payment_hub"
    include data_object
}

view container payment_containers "Container Details" {
    include app where owner == "Payments Team"
}

• Change an application property or relationship once, and every view referencing it updates automatically.

---

2. Beyond Software: Full Enterprise Architecture Scope

Structurizr (C4 Model)

Structurizr pioneered moving from isolated diagrams to a shared model using Simon Brown's C4 model (Context, Containers, Components, Code).

While C4 is excellent for individual software applications, it deliberately avoids enterprise architecture concerns:

• C4 has no concept of Business Capabilities, Value Streams, or Strategic Goals.
• C4 has no native modeling for Infrastructure Nodes, Hosting Environments, or Data Classifications.
• C4 lacks formal threat modeling (e.g. STRIDE classifications, risk ratings, security controls).

Scapius

Scapius provides a complete enterprise scope grounded in The Open Group ArchiMate 3.2:

• Strategy: Model Business Goals, KPIs, Capabilities, and Value Stream stages.
• Business: Model Actors, Roles, and Business Processes.
• Applications: Model Systems, Applications, Components, and modern Autonomous AI Agents.
• Technology: Model Environments, Cloud Infrastructure, and Network Boundaries.
• Security & Governance: Model STRIDE Threats, Risk Scenarios, Compliance Standards, and Mitigating Controls.

---

3. Formal Compiler vs. Generic Shape Connectors

In PlantUML or Mermaid, there are no domain rules. You can connect an arbitrary rectangle to an oval and label it with anything:

graph TD
  Firewall -->|realizes| CompanyGoal

The diagram renderer happily draws it, even though semantically a firewall cannot "realize" a corporate goal.

Scapius is a typed, validating architecture compiler:

• The compiler understands the semantics of all 21 entity types and 16 relationship verbs.
• If a model declares an illegal relationship (e.g. control mitigates capability instead of threat), the compiler reports an error with line and column numbers.
• You catch architecture violations in your pull request before anyone views a misleading diagram.

---

4. Deterministic Layout & Visual Persistence

A frequent frustration with auto-layout tools (like Graphviz under PlantUML) is layout instability: adding a single connection can cause the entire diagram to flip orientation or scramble nodes across the canvas.

Scapius provides:

• Clean automatic layout as a baseline.
• Persistent interactive layout: Move nodes, arrange boundaries, and position clusters in the Scapius viewer—your spatial layout is saved and survives future model recompilations.
• Predicate styling: Color-code nodes based on attributes (e.g., where criticality == "Mission-Critical" or where internet_facing == true) without hardcoding colors on entities.

---

Summary

Use Case	Recommended Tool
Quick sketch in a GitHub README or issue	Mermaid.js
Documenting internal class/component diagrams for a single repository	PlantUML or Structurizr
Modeling enterprise systems, capabilities, data flows, security, and multi-team architectures	Scapius