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:

1. Root Workspace (main.ea): Exactly one file contains the workspace <Name> { ... } declaration. It defines global styling, themes, and shared views.
2. 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 "rounded_rectangle"
            css_class "card border-secondary text-primary"
        }

        style "actor" {
            shape "person"
            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

            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"
        tier "Tier-1"
        time "Eliminate"
        cost {
            amount 1200000
            unit year
        }
        score {
            business_value 9.0
            tech_fit 4.5
        }
        security {
            confidentiality "High"
            integrity "Critical"
            availability "Critical"
        }
        lifecycle {
            phase Run start "2010-01-01" end "2026-12-31"
            phase Retire start "2027-01-01"
        }

        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
            status "Active"
            time "Invest"
            cost {
                amount 350000
                unit year
            }
            score {
                business_value 9.5
                tech_fit 9.0
            }
            security {
                confidentiality "High"
                integrity "Critical"
                availability "Critical"
            }
            lifecycle {
                phase Run start "2022-01-01"
            }

            relationships {
                this serves customer "Provides self-service mobile banking"
            }
        }
    }
}

---

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:

Click to explore

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

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.