Skip to main content

Quick Start (5 Minutes)

In this quick tutorial, you will create and validate your first .ea architecture model describing a customer checkout workflow, payment service, and PCI compliance controls.

Step 1: Create a Model File​

  • Create a new folder named workspace in your working directory.
  • Create a new file named main.ea in the above workspace directory:
workspace quickstart_architecture "Quickstart Example" {

    layer "Business Layer" {
        actor customer "Online Shopper" {
            description "End-user purchasing items online"
            role "Consumer"
            is_external true

            relationships {
                this triggers checkout_flow "Initiates checkout process"
            }
        }

        process checkout_flow "Checkout Process" {
            description "User purchasing items through digital cart"
            risk "Low"
            criticality "Mission-Critical"
            automation_level "High"

            relationships {
                this triggers payment_gateway "Submits payment order"
            }
        }
    }

    layer "Application Layer" {
        system payment_gateway "Payment Gateway System" {
            description "Central system handling payment tokenization and settlements"
            tier "Tier-1"
            internet_facing true
            risk "Medium"
            time "Invest"
            cost 100000 year
            status "Active"
            criticality "Mission-Critical"

            app payment_api "Payment REST API" {
                attr technology "ASP.NET Core / .NET 10"
                attr api_type "REST"
                internet_facing true
                status "Active"

                component token_handler "Tokenization Module" {
                    technology "C#"
                }
            }

            relationships {
                this reads transaction_data "Reads payment details"
                this writes transaction_data "Persists transaction state"
                this serves checkout_flow "Processes payment for checkout"
            }
        }

        data_object transaction_data "Transaction Record" {
            classification "Confidential"
            pii true
            phi false
        }
    }

    views {
        landscape payment_system "Payment System Overview" {
            include payment_gateway
            include customer
            include checkout_flow
            auto_layout LeftToRight
        }

        data_flow payment_flow "Payment Flow" {
            include payment_gateway
            include transaction_data
            auto_layout TopToBottom
        }
    }
}

Step 2: Validate the Model with Scapius Community Edition​

Run the scapius validate command using the Scapius Community Edition Docker container:

docker run --rm -v ./workspace:/workspace ghcr.io/scapius-ea/scapius-community validate -v /workspace

You should see output indicating successful validation:

Validation Successful! Workspace 'Quickstart Example' is valid.
[Info] Processing file 'main.ea'...
[Info] Executing phase 'EntityMapping'...
[Info] Phase 'EntityMapping' completed.
[Info] Executing phase 'SemanticLinking'...
[Info] Phase 'SemanticLinking' completed.
[Info] Executing phase 'PropertyInheritance'...
[Info] Phase 'PropertyInheritance' completed.
[Info] Executing phase 'CapabilityNumbering'...
[Info] Phase 'CapabilityNumbering' completed.
[Info] Executing phase 'ConstraintValidation'...
[Info] Phase 'ConstraintValidation' completed.
[Info] Executing phase 'GlobalUniqueness'...
[Info] Phase 'GlobalUniqueness' completed.
[Info] Phase compile completed for workspace 'Quickstart Example'.

Step 3: Test Semantic Validation​

To see Scapius semantic validation in action, let's intentionally introduce an invalid relationship.

Add this line inside the relationships block of the customer entity:

actor customer "Online Shopper" {
    relationships {
        this triggers checkout_flow "Initiates checkout process"
        this composed_of payment_gateway  // Invalid! An actor cannot compose a system
    }
}

Now re-run the validator:

docker run --rm -v ./workspace:/workspace ghcr.io/scapius-ea/scapius-community validate -v /workspace
Validation Failed!
[Info] Processing file 'main.ea'...
[Info] Executing phase 'EntityMapping'...
[Info] Phase 'EntityMapping' completed.
[Info] Executing phase 'SemanticLinking'...
[Error] main.ea Line 11: Relationship 'customer composed_of payment_gateway' is invalid. Entity type 'System' cannot be a sub-object of 'Actor'.
[Info] Phase 'SemanticLinking' completed.
[Info] Executing phase 'PropertyInheritance'...
[Info] Phase 'PropertyInheritance' completed.
[Info] Executing phase 'CapabilityNumbering'...
[Info] Phase 'CapabilityNumbering' completed.
[Info] Executing phase 'ConstraintValidation'...
[Info] Phase 'ConstraintValidation' completed.
[Info] Executing phase 'GlobalUniqueness'...
[Info] Phase 'GlobalUniqueness' completed.
[Info] Phase compile completed for workspace 'Quickstart Example'.

Scapius prevents structurally invalid architectural representations at compile-time! Remove the invalid line to return the file to a clean state.

Next Steps​