> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dalus.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Structural Modeling
> How to create Parts, Ports, Interfaces, and Connections to model the physical and logical architecture of your system
Structural modeling in Dalus allows you to define the physical and logical architecture of your system through interconnected components. Build hierarchical systems by creating parts, connecting them through ports and interfaces, and organizing flows with visual color coding.
## System Architecture Overview
Dalus provides a complete canvas for modeling complex systems with hierarchical organization. The left sidebar shows your model hierarchy, making it easy to navigate between different levels of your system. Toggle between different views to focus on structural elements, behaviors, or states.
## What are Parts
Parts are the fundamental building blocks of your system—representing physical components, logical modules, or any architectural element. Each part can contain nested sub-parts, creating a hierarchical decomposition of your system. Parts connect to other parts through ports and can have attributes (variables) that define their properties.
**Key characteristics of Parts:**
* Represent physical components (sensors, actuators, processors) or logical modules (software components, subsystems)
* Can be nested to create hierarchical system breakdowns
* Connect to other parts via ports and interfaces
* Can have attributes assigned to capture properties like mass, power consumption, or dimensions
* Can be linked to requirements for traceability
## Creating Parts
Create parts using the toolbar on the left side of the canvas or keyboard shortcuts:
| Method | How |
| ------------ | -------------------------------- |
| Toolbar | Click the Part button |
| Keyboard | Press `P` |
| Context Menu | Right-click on canvas → Add Part |
Name parts by clicking their label and typing directly. Use descriptive names that reflect the component's function or identity.
**Double-click any part to open it in a new tab** and work within its internal structure. This allows you to build nested hierarchies where each part can contain its own sub-parts, actions, and states.
## Part Properties and Attributes
When you select a part, the right sidebar displays all its properties:
* **Label**: The part's display name
* **Description**: Detailed description of the part's purpose and function
* **Attributes**: Variables assigned to the part (mass, dimensions, power ratings, etc.)
* **Sub-Parts**: Nested parts contained within this part
* **Ports**: Connection points defined on this part
* **Actions**: Behaviors and computations associated with this part
* **States**: Operational modes and conditions
* **Notes**: Additional documentation
### Adding Attributes
Attributes are variables that capture quantitative properties of a part. Click **Add Attribute** in the right sidebar to create new attributes:
1. Provide a descriptive name (use lowercase snake\_case, e.g., `total_mass`, `power_consumption`)
2. Set the value and expression
3. Specify the unit (meters, kilograms, watts, etc.)
4. Optionally add a prefix for SI units (kilo, mega, milli)
Attributes enable your model to carry quantitative data that can be used in calculations, trade studies, and constraint verification.
**Using the Expression Editor**: Attributes support mathematical expressions that reference other variables. Click the expression field to open the Expression Editor, where you can build formulas using operators (`+`, `-`, `*`, `/`, `^`) and reference other variables by name. For example, set `total_mass` to `dry_mass + fuel_mass` and it will automatically update when either value changes.
### Linking Existing Variables
Instead of creating a new attribute, you can link to an existing variable from anywhere in your model. Click the link icon next to the attribute field to open the variable search. Search by name or browse through available variables—including attributes from other parts, action outputs, and interface connections. Select a variable to link it directly to your part.
### Adding Visuals to Parts
Enhance your parts with visual representations to make your model more intuitive and recognizable. Right-click on a part node and select **Add Visual** to attach an image. You can:
* **Upload an image**: Add a custom image file (PNG, JPG, SVG) to represent the component
* **Choose from the library**: Select from previously uploaded images in your workspace
* **Use AI generation**: Generate an image using AI based on a description of your part
* **Link from URL**: Reference an external image by URL
Visuals appear on the part node in the canvas, making it easier to identify components at a glance—especially useful for physical systems where visual recognition speeds up navigation.
## What are Ports
Ports define connection points on parts where interfaces attach. They represent the boundary of a part—where information, energy, or matter flows in or out. Every connection between parts must go through ports.
**Port characteristics:**
* Always belong to a parent part
* Snap to part edges for clean visual organization
* Can be inputs, outputs, or bidirectional
* Multiple ports can exist on a single part
* Serve as anchors for interface connections
## Creating Ports
Create ports using these methods:
| Method | How |
| ------------ | -------------------------------- |
| Toolbar | Click the Port button |
| Keyboard | Press `O` |
| Context Menu | Right-click on a part → Add Port |
Ports automatically snap to the edges of parts. Position them logically—inputs on one side, outputs on another—to create readable diagrams.
## What are Interfaces
Interfaces are edges that connect two ports, defining the relationship and data flow between parts. Each interface can contain multiple connections that specify exactly what flows between the connected parts.
**Interface characteristics:**
* Connect exactly two ports (source and target)
* Can contain multiple connections of different types
* Support color grouping for visual organization
* Can be saved as templates for reuse
## Creating Interfaces
To create an interface:
1. Click and drag from one port
2. Connect to another port on a different part
3. Release to create the interface edge
The interface appears as a line connecting the two ports. Select it to configure its connections in the right sidebar.
Ports belonging to the same part cannot be connected to each other. Interfaces always connect ports on different parts.
## Creating Connections
Connections define the specific flows within interfaces. Each connection specifies:
* **Name**: Descriptive name for the flow (lowercase snake\_case)
* **Type**: The category of flow
* **Direction**: `in`, `out`, or `both`
* **Variable**: The quantitative value being transferred
* **Properties**: Additional variables for secondary quantities
### Connection Types
Dalus supports five primary connection types:
| Type | Description | Examples |
| --------------- | --------------------------------- | -------------------------------------------------- |
| **Energy** | Power and energy transfer | Electrical current, mechanical force, thermal heat |
| **Matter** | Physical material flow | Fuel, coolant, hydraulic fluid, air |
| **Information** | Data and signal transfer | Commands, sensor readings, status signals |
| **Message** | Discrete event or mission message | Alerts, mission messages |
| **Binding** | Physical attachment | Mechanical fasteners, welds, adhesive bonds |
Each type can have subtypes for more specific categorization (e.g., Energy → Electrical, Energy → Mechanical).
### Connection Variables and Properties
Every connection has:
* **Primary Variable** (`variableId`): The main quantity being transferred (e.g., electrical current in amps)
* **Properties** (`propertyIds`): Secondary quantities that characterize the flow (e.g., voltage, frequency)
This allows rich modeling of interfaces where multiple related quantities flow together.
## Color Groups
Organize complex interfaces using color groups for visual coding. Assign colors to related flows to make large systems easier to understand and navigate.
**Best practices for color coding:**
* Use consistent colors across your model for similar flow types
* Group related connections under the same color
* Choose high-contrast colors for critical interfaces
* Document your color scheme for team consistency
## Interface Templates
Save frequently used interface configurations as templates for reuse across your models. Build a library of standard interface types for your domain to maintain consistency.
**To save a template:**
1. Configure an interface with all desired connections
2. Click the Save Template option
3. Provide a descriptive name
**To load a template:**
1. Select an interface
2. Click Load Template
3. Choose from your saved templates
Templates help enforce organizational standards and speed up modeling of common interfaces.
## Navigating Hierarchical Models
Dalus supports deep hierarchical nesting. Navigate effectively using:
### Drill-Down Navigation
* **Double-click** a part to enter it and view its internal structure
* The tab header shows breadcrumb navigation for your current location
* Click any breadcrumb to jump back to that level
### View Modes
Toggle view modes to focus on different aspects:
* **Part View**: Show structural elements (Parts, Ports, Interfaces)
* **State View**: Show state machines (States, Transitions)
* **Action View**: Show behaviors (Actions, Signals)
### Left Sidebar Hierarchy
The model tree in the left sidebar provides:
* Expandable/collapsible hierarchy
* Filter by element type
* Quick navigation to any element
* Search across all elements
## Linking Parts to Requirements
Parts can be assigned to requirements for complete traceability:
1. Open a requirement in the Requirements page
2. Use the **Assigned Systems** menu to link parts
3. Assignments appear as badges on both the requirement and part
This creates bidirectional traceability—from requirements to implementing parts, and from parts to the requirements they satisfy.
## Keyboard Shortcuts
Master these shortcuts for efficient structural modeling:
| Shortcut | Action |
| ---------------------- | --------------------------- |
| `P` | Create Part |
| `O` | Create Port |
| `B` | Build mode (default cursor) |
| `H` | Hand tool (pan mode) |
| `Space` (hold) | Temporary hand tool |
| `Delete` / `Backspace` | Delete selected elements |
| `Cmd/Ctrl + Click` | Multi-select elements |
| `Shift + Click` | Add to selection |
| `Double-click` | Open element in new tab |
| `Cmd/Ctrl + Z` | Undo |
| `Cmd/Ctrl + Shift + Z` | Redo |
| `Cmd/Ctrl + K` | Global search |
| `Escape` | Cancel current operation |
## Copy, Paste, and Duplication
Duplicate parts and their internal structure:
1. Select one or more parts (use `Shift` or `Cmd/Ctrl + Click` for multi-select)
2. Copy with `Cmd/Ctrl + C`
3. Paste with `Cmd/Ctrl + V`
Pasting duplicates the complete structure including:
* All nested sub-parts
* Ports and their positions
* Internal interfaces and connections
* Attributes and variables
* Associated actions and states
## Using AI for Structural Modeling
The Dalus AI Copilot accelerates structural modeling tasks:
### Subsystem Decomposition
Ask Copilot to break down a part into its constituent subsystems:
* *"Break down the Power System into its subsystems"*
* *"Create a functional decomposition of the Flight Computer"*
### Interface Generation
Let AI create interfaces between subsystems:
* *"Create interfaces between the subsystems of the Propulsion Module"*
* *"Add connections for power and data between these components"*
### Architecture from Requirements
Generate structural elements from requirement statements:
* *"Create parts to satisfy these interface requirements"*
* *"What subsystems are needed to meet the performance requirements?"*
### Model Queries
Ask questions about your architecture:
* *"What parts receive power from the Main Bus?"*
* *"Show me all interfaces that carry thermal data"*
## Collaboration
Dalus supports real-time collaboration on structural models:
* **Live Cursors**: See where other team members are working
* **Simultaneous Editing**: Multiple users can edit different parts of the model
* **Automatic Conflict Resolution**: System handles concurrent edits gracefully
* **Snapshots**: Save model states for version tracking
Invite collaborators via the Share button in the left sidebar.
## Essential Tips
1. **Plan your hierarchy first**: Sketch the high-level decomposition before diving into details
2. **Use consistent naming**: Establish naming conventions for parts, ports, and interfaces
3. **Model incrementally**: Build and validate small sections before connecting them
4. **Leverage templates**: Save common interface patterns as templates
5. **Document as you go**: Use descriptions and notes to capture design rationale
6. **Link to requirements early**: Establish traceability while the design intent is fresh
7. **Use color coding**: Develop a consistent color scheme for interface types
8. **Keep ports organized**: Position inputs and outputs consistently across parts
This structural modeling approach enables you to build well-organized, analyzable system architectures with clear relationships between all components.