Tutorial 1: Multi-File Setup & Your First Model

In this tutorial, you will set up a real-world enterprise architecture repository for NeoBank — a modern digital bank running cloud-native microservices alongside a core banking mainframe.

You will establish a multi-file workspace structure right from the start, author your first domain entities, and project an interactive Landscape View complete with sticky note annotations.

1. Multi-File Architecture in Scapius

Scapius is designed from the ground up for collaborative, multi-file architecture repositories:

Root Workspace (main.ea): Exactly one file contains the workspace <Name> { ... } declaration. It defines global styling, themes, and shared views.
Workspace Fragments (*.ea): All other .ea files in the repository contain bare statements (entities, relationships, or local views). When you validate or run Scapius, it automatically discovers main.ea and seamlessly aggregates all fragments into a unified architecture graph.

Start by creating the initial directory layout for NeoBank:

neobank/
├── main.ea                               # Root workspace definition, styles, and views
└── application/
    └── customer_onboarding.ea            # Domain fragment: onboarding apps & customer actor

2. Define the Root Workspace (`main.ea`)

Create main.ea at the root of the neobank/ folder. This file declares the neo_bank workspace, sets up default node styling, and specifies our first projection view:

neobank/main.ea
workspace neo_bank "Neo Bank Enterprise Architecture" {

    styles {
        style "system" {
            shape "rounded_rectangle"
            css_class "card shadow-sm border-primary"
        }

        style "app" {
            shape "pill"
            css_class "card border-secondary text-primary"
        }

        style "actor" {
            shape "actor"
            css_class "actor-node text-center"
        }
    }

    views {
        landscape customer_onboarding_context "Customer Onboarding Context" {
            description "End-to-end customer onboarding journey across digital channels, core deposit services, and KYC records."
            tags ["Customer Experience", "KYC", "Onboarding", "Journey"]

            include customer
            include app_mobile_banking
            include system_core_banking
            include data_customer_record

            auto_layout TopToBottom

            text onboardingNote """
                Frictionless mobile onboarding backed by instant identity checks reduces customer registration to under 5 minutes.
            """ {
                anchor customer
            }
        }
    }
}

3. Create the Domain Fragment (`application/customer_onboarding.ea`)

Next, create application/customer_onboarding.ea. Notice that this file is a workspace fragment — it does not repeat the workspace { } wrapper. It defines the customer actor, mobile application, core banking engine, and customer KYC record:

neobank/application/customer_onboarding.ea
layer "Application Architecture" {

    actor customer "Retail Customer" {
        description "Prospective and active personal banking customers accessing NeoBank digital channels"
        role "Customer"
        is_external true
    }

    system system_core_banking "Core Banking Platform" {
        description "Central mainframe-based account ledger, settlement system, and records database"
        owner "Core Banking Operations"
        criticality "Mission-Critical"
        status "Active"
    }

    app app_mobile_banking "NeoBank Mobile App" {
        description "Primary customer-facing digital touchpoint for onboarding, deposits, and transfers"
        owner "Digital Channels"
        tier "Tier-1"
        internet_facing true

        relationships {
            this serves customer "Provides self-service mobile banking"
            this flows_to system_core_banking "Posts onboarding registration transactions"
            this writes data_customer_record "Persists customer KYC profile"
        }
    }

    data_object data_customer_record "Customer Profile & KYC Record" {
        description "Customer master record containing verified identity, KYC status, and contact details"
        classification "Restricted"
        pii true
    }
}

4. Visual Projection: `customer_onboarding_context`

The landscape view projects the entities and their directional relationships, automatically positioning nodes using the TopToBottom hierarchical layout algorithm and placing the sticky note next to the customer anchor node:

Customer Onboarding Context landscape view showing actor, mobile app, core mainframe, and KYC data record

Key Features Promoted in this View:

Explicit Inclusions (include <id>): Focus the diagram precisely on the entities relevant to the onboarding narrative without clutter from other subsystems.
Hierarchical Layout (auto_layout TopToBottom): Automatically generates readable top-to-bottom interaction flows from the end-user down to transactional records.
Sticky Note Annotations (text <id> """...""" { anchor <node> }): Attach narrative commentary and architectural decisions directly to diagram elements.

5. Validate the Multi-File Workspace

Run the Scapius CLI validate command against the neobank/ folder:

scapius validate ./neobank

Validation Successful! Workspace 'Neo Bank Enterprise Architecture' is valid.

Scapius parses main.ea, discovers all fragment files in the directory tree, resolves cross-file identifiers, and confirms the integrity of all relationships.

Next Steps

Now that you have a working multi-file workspace and your first landscape view, continue to Tutorial 2: Layered Architecture to structure NeoBank across Strategy, Business, Application, and Technology layers.

1. Multi-File Architecture in Scapius​

2. Define the Root Workspace (main.ea)​

3. Create the Domain Fragment (application/customer_onboarding.ea)​

4. Visual Projection: customer_onboarding_context​

Key Features Promoted in this View:​

5. Validate the Multi-File Workspace​

Next Steps​