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 file named quickstart.ea in your working directory:

workspace quickstart_architecture "Quickstart Example" {

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

        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"
            criticality "Mission-Critical"

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

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

            relationships {
                this reads transaction_data "Reads payment details"
                this writes transaction_data "Persists transaction state"
            }
        }

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

    layer "Security Layer" {
        policy pci_compliance "PCI-DSS 4.0 Standard" {
            policy_type "Security"
            enforcement "Mandatory"
            priority "Critical"
        }

        control tokenization_control "Card Data Tokenization" {
            control_type "Preventive"
            control_category "Cryptography"
            implementation_status "Implemented"
            effectiveness "High"

            relationships {
                this governed_by pci_compliance "Enforces compliance"
                this protects transaction_data "Masks sensitive cardholder info" { mechanism "Encryption" }
            }
        }
    }

    styles {
        style system where tier == "Tier-1" {
            css_class "tier-1-highlight"
            icon "shield-check"
        }
    }
}

Step 2: Validate the Model with Docker​

Run the scapius validate command via Docker:

docker run --rm -v $(pwd):/workspace scapiusea/scapius validate /workspace/quickstart.ea

You should see output indicating successful validation:

✓ Parsing 'quickstart.ea'...
✓ AST successfully generated (23 AST nodes)
✓ Running semantic checks & relationship resolution...
✓ Global uniqueness phase: 0 collisions
✓ Semantic linking phase: 8 relationships resolved
✓ Style rules compilation: 1 style rule resolved
✓ Validation completed: 0 errors, 0 warnings

Step 3: Test Semantic Validation​

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

Add this line inside the customer entity:

actor customer "Online Shopper" {
    relationships {
        this composed_of payment_gateway  # Invalid! An actor cannot compose a system
    }
}

Now re-run the validator:

docker run --rm -v $(pwd):/workspace scapiusea/scapius validate /workspace/quickstart.ea
✗ Validation failed:
[Error NEA3004] Linking Error: Relationship 'customer composed_of payment_gateway' is invalid. Entity type 'System' cannot be a sub-object of 'Actor'.
  --> quickstart.ea:8:9

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

Next Steps​