Your First Project

This guide walks you through creating a minimal ArchTect workspace from scratch.

1. Create a DSL file

Create a file called workspace.dsl and paste the following:

workspace "My First Architecture" "A simple system context example" {
  model {
    user = person "User" "A user of the system"
    system = softwareSystem "My System" "The system being modeled"
    user -> system "Uses"
  }

  views {
    systemContext system "SystemContext" {
      include *
      autoLayout
    }
  }
}

This defines:

• A person called “User”
• A software system called “My System”
• A relationship between them (“Uses”)
• A system context view that includes all elements

2. Open in ArchTect

VS Code extension:

1. Open the folder containing workspace.dsl in VS Code.
2. Open the .dsl file — the ArchTect icon appears in the editor title bar (top right).
3. Click the icon to open the visual canvas editor.

You can also right-click the file in the Explorer and choose ArchTect: Open with ArchTect.

Browser app:

1. Open the ArchTect web app.
2. Open or upload your workspace.dsl file.

3. Explore the diagram

Once the file is loaded, open the left rail’s Views panel and click SystemContext to open the view you defined:

• The canvas shows your system context diagram with the User and My System elements.
• Click on an element to see its properties in the Inspector.
• The Views panel lists both your authored view and views ArchTect auto-generates (tagged AUTO) alongside it.

4. Add an element visually

Try adding a new element using drag-and-drop:

1. Use the element palette or toolbar to add a new Software System to the canvas.
2. Drag it into position.
3. Create a relationship by dragging from one element to another.
4. Edit the name and description in the Inspector.

The DSL updates automatically to reflect your visual changes — this is the bidirectional sync in action.

Tip

DSL editing works too

You can also edit the DSL directly. For example, add a database to the model:

db = softwareSystem "Database" "Stores data"
system -> db "Reads from and writes to"

The canvas updates to show the new element and relationship.

5. Your changes are saved

Changes you make on the canvas or in the DSL editor are synced to the underlying .dsl file automatically. In VS Code, the file tab may show as modified — use Ctrl+S / Cmd+S to flush it to disk.

Tip

Next level

Once you’re comfortable with this basic workspace, try adding containers inside your software system, creating a container view, and applying styles to differentiate element types visually.

Next steps

• UI Tour — Learn the main areas of the interface.
• DSL Basics — Learn more DSL syntax: containers, components, groups, and tags.
• Views — Understand the different view types and when to use them.
• Export — Export your diagrams as PNG, SVG, or other formats.