UI Navigation

UI Navigation

This page describes the complete navigation flow of the Vitruv-UI-Methodologist frontend — which screens exist, how a user moves between them, and what each screen does.

---

Navigation flow

flowchart TD
    A([User opens app]) --> B{Authenticated\n& verified?}

    B -->|No| C["/login — Auth screen"]
    B -->|Yes| H

    C --> C1["Sign In form"]
    C --> C2["Sign Up form"]
    C --> C3["KIT / Keycloak SSO\n/auth"]

    C1 -->|Email not yet verified| D
    C2 -->|Registration complete| D
    C3 -->|Callback: /auth/callback| D
    C1 -->|Already verified| H

    D["/verify-otp — Email verification"]
    D -->|Code accepted| H

    H["/ — Home\n(sidebar layout)"]

    H --> H1["Home tab\nWelcome & quick links"]
    H --> H2["Model Library tab\nBrowse & upload metamodels"]
    H --> H3["Projects tab\nCreate & open VSUMs"]
    H --> H4["Profile tab\nEdit name & password"]

    H3 -->|Double-click or open project| K

    K["/canvas/:id — Canvas"]

    K --> K1["Modeling mode\n(default)"]
    K --> K2["Constraints mode"]
    K --> K3["Views mode"]

    K1 --> L1["Model Drawer\nAdd metamodels to canvas"]
    K1 --> L2["Draw reaction edge\nbetween two models"]
    K1 --> L3["UML panel\nFloating class diagram view"]
    K1 --> L4["Code Editor modal\nEdit .reactions file"]

    K --> M1["Save button\nPersists canvas to backend"]
    K --> M2["Check Build button\nValidates VSUM config"]
    K --> M3["Download button\nExports artifact as .zip"]

    K --> O["Project tabs\nSwitch between open VSUMs"]
    K -->|Back button / logo| H

    H4 --> P["Change Password modal"]
    H4 -->|Log out| C

Loading

---

Screen descriptions

/login — Auth screen

The entry point for unauthenticated users. Presents two tabs:

• Sign In — username and password login with a "keep me signed in" option and a forgot-password flow (sends a reset email)
• Sign Up — registration form; submitting redirects to the OTP verification screen

A third path is available via Keycloak SSO (KIT login), which redirects to /auth and returns via /auth/callback.

Unauthenticated requests to any protected route redirect here automatically.

---

/verify-otp — Email verification

Required for new registrations and for sign-ins where the account email has not yet been confirmed. The user enters a 6-character code sent to their registered email address.

• Code is valid for 5 minutes, displayed as a live countdown
• Up to 2 attempts before a resend is required
• A new code invalidates all previous codes
• On success, the user is redirected to the Home screen

---

/ — Home

The main dashboard after login. A dedicated landing page with project-specific information.

Home tab

A welcome screen with two quick-access cards (Projects and Model Library) and a short description of the Vitruvius framework. Starting point after every login.

Model Library tab

A searchable table of all metamodels available to the user — both their own uploads and public models shared in the system. From here a methodologist can:

• upload a new .ecore metamodel file
• view, edit metadata (name, description, keywords, domain), or delete an existing model
• download the raw .ecore file

Projects tab

A table of all VSUM projects the user owns or is a member of. Each row shows the project name, role (Owner / Member), and creation date. Actions:

• double-click a row → opens the canvas for that VSUM
• Details → opens a modal with member management and metadata editing
• Delete → soft-deletes the project (recoverable for 30 days)

A "Create new project" button opens a modal to name and create a new VSUM.

Profile tab

Displays the current user's name, username, email, and role. Allows editing first and last name. A "Change Password" button opens an inline modal with current-password verification.

---

/canvas/:id — Canvas

The primary working environment. The URL parameter :id is the VSUM's numeric ID.

The canvas is split into three modes, switchable via a toggle at the top center:

Modeling mode (default)

The main authoring view. Metamodels appear as UML class diagram boxes on a ReactFlow canvas. The methodologist:

• adds metamodels via the Model Drawer (a modal showing models from the project and the library)
• draws reaction edges between two metamodel boxes by enabling reaction mode and clicking the source and target
• expands a UML panel by clicking the expand icon on any metamodel box — opens a floating, resizable panel with the full class diagram
• opens the Code Editor on any reaction edge to read or edit the generated .reactions file with syntax highlighting and LSP support

The left toolbar provides: Select mode, Save, Check Build, Download artifact, Add Reaction, Add Metamodel, Undo, Redo.

The top-left pill shows the current project name (editable via the pencil icon) and a back button.

Constraints mode

An overlay that displays the current canvas nodes in a constraint-editing view. Used to define additional consistency constraints between metamodels.

Views mode

Allows defining ViewTypes that describe how model views are composed from the VSUM

Project tabs

Multiple VSUMs can be open simultaneously in named tabs below the mode toggle. Switching tabs restores the previous session state from memory. Unsaved changes are indicated with a dot on the tab; closing a dirty tab prompts a save dialog.

---

Key interactions at a glance

Action	How
Open a project	Projects tab → double-click row
Add a metamodel to the canvas	Canvas → toolbar "+ metamodels" → Model Drawer
Connect two metamodels	Canvas → toolbar reaction button → click source → click target
Edit the generated reaction code	Click a reaction edge → "Open Editor"
Save canvas state	Canvas → toolbar save icon (or Ctrl+S)
Validate the VSUM config	Canvas → toolbar checkmark icon
Download the built artifact	Canvas → toolbar download icon
Switch between open projects	Project tabs strip below the mode toggle
Edit profile / change password	Home → Profile tab
Log out	Home → sidebar bottom → Log out