Insight Language

1. Overview

Insight is a domain-specific language (DSL) for modeling IT architecture. It uses indentation to define block structure, where one level of nesting is represented by one tab or four spaces. Each statement in Insight ends with a newline, with no need for additional delimiters like semicolons or braces.

The language is case-sensitive, meaning keywords, identifiers, and references must be written with consistent capitalization. Identifiers can contain letters (a-z), numbers (0-9), and underscores (_), but they must always start with a lowercase letter.

Insight does not use special characters to delimit strings. A single-line text ends with a newline character. Multi-line text requires indentation on the next line and continues until the indentation returns to the level that is less or equal to the previous one.

2. Core Elements

2.1 context

  • Purpose: Defines a bounded context, representing a specific domain within an architectural model. It serves as a high-level grouping of systems and actors that interact within a defined scope.
  • Usage: Must appear at the top level of an Insight file. May be described in a single file or split across multiple files for convenience. In this case all files will have a shared context diagram and separate container diagrams.
  • Syntax:
context <identifier>
  [block]
    • <identifier>: A name that uniquely identifies this bounded context.

2.2 system

  • Purpose: Represents a software system within a bounded context. A system consists of multiple containers, such as microservices, databases, or other software components. It defines the major building blocks of the architecture at a high level.
  • Usage: A context block may contain one or more systems, which can optionally be marked as external. Each system must have an identifier and a name parameter. Additionally, a system can be annotated with one or more annotations.
  • Syntax:
[@annotation]
[external] system <identifier> [# optional note for current element]
  INDENT
    <name parameter>
    [technology parameter]
    [description parameter]
    [links declaration]
  DEDENT
  • Example:
system target
    name = Target system
    technology = Java, Micronaut
    description = Receives requests

2.3 external

  • Purpose: Used to mark systems that are outside the current context. By default, all imported systems in a file are considered external.
    A system can also be explicitly marked as external if it represents an external third-party service that interacts with the systems inside the context. Typical examples include Google services or GitHub API.
  • Usage: Placed immediately before the system keyword.
  • Syntax:
[external] system <identifier>
  • Example:
external system google
    name = Google ID
    description = Oauth 2.0 provider

2.4 actor

  • Purpose: Represents a user or role that interacts with one or more systems within a context. Actors define how external entities engage with the architecture, whether as end users, administrators, automated processes, or other interacting parties.
  • Usage: A context block may contain one or more actors. Each actor must have an identifier and a name parameter. Additionally, an actor can be annotated with one or more annotations.
  • Syntax:
[@annotation]
actor <identifier> [# optional note for current element]
  INDENT
    <name parameter>
    [technology parameter]
    [description parameter]
    [links declaration]
  DEDENT
  • Example:
actor user
    name = 👤 Arcinsight user
    technology = Web browser

2.5 service

  • Purpose: Represents a container-level entity that defines a fundamental unit of an IT system. In most cases, this corresponds to a single microservice, but it can also represent any independently deployable and executable component.
  • Usage: A service must be defined inside a system and serves as a building block that encapsulates specific functionality. Each service must have an identifier and a name parameter. Additionally, a service can be annotated with one or more annotations.
  • Syntax:
[@annotation]
service <identifier> [# optional note for current element]
  INDENT
    <name parameter>
    [technology parameter]
    [description parameter]
    [links declaration]
  DEDENT
  • Example:
service editor_back
    name = Editor-UI
    technology = Java, Vaadin, Micronaut
    description = Serves application frontend logic and static data

2.6 storage

  • Purpose: Represents a container-level entity responsible for data persistence within a system. It can define various types of storage solutions, such as databases, caches or file storage systems.
  • Usage: A storage must be defined inside a system. Each storage must have an identifier and at least one parameter. Additionally, a storage can be annotated with one or more annotations.
  • Syntax:
[@annotation]
storage <identifier> [# optional note for current element]
  INDENT
    [name parameter]
    [technology parameter]
    [description parameter]
    [links declaration]
  DEDENT
  • Example:
storage repository_store
    technology = Postgres
    description = Tables:
        - repository: contains repository file system data
        - file: contains raw file data

3. Parameters

Parameters are defined inside the entity block with indentation following an entity declaration (system, actor, service, storage or communications). They must have unique names within the same block. A parameter can be annotated with one or more annotations.

The syntax for all parameters follows the same pattern:

[@annotation]
<identifier> = value

3.1 name

  • Purpose: A human-readable name for the element.
  • Usage: Required after system, actor and service. Optional for storage. Not expected for communications.

3.2 description

  • Purpose: Any additional information, such as the purpose or function of the element.
  • Usage: Optional for any kind of element.

3.3 technology

  • Purpose: The technologies or protocols used (e.g., HTTP, Java, PostgreSQL).
  • Usage: Optional for any kind of element.

3.4 call

  • Purpose: The API method invoked during interactions.
  • Usage: For synchronous communications only

3.5 format

  • Purpose: The name of the data model used in interactions.
  • Usage: May be set for any type of communications.

3.6 via

  • Purpose: The communication channel or message broker topic through which interactions occur.
  • Usage: For asynchronous communications only

4. Communications (Wire Declarations)

  • Purpose: Defines all network interactions between the current element and other entities. The direction of described communication always corresponds to the direction of network connection establishment.
  • Usage: A links block can be used inside system, actor, service, and storage elements after all parameters. This block is always optional.
  • Syntax:
links:
  INDENT
    [synchronous communication]
    [asynchronous communication]
  DEDENT
  • Example
links:
    -> renderer
    ~> repository

4.2 -> Synchronous communication

  • Purpose: Represents a synchronous interaction, such as an HTTP request or a direct API call.
  • Usage: A synchronous communication must be defined inside a links block. Each definition must reference either an identifier or an anonymous import statement. Additionally, it can be annotated with one or more annotations.
  • Syntax:
[@annotation]
-> <identifier> [from <identifier>]
  INDENT
    [model parameter]
    [technology parameter]
    [description parameter]
    [call parameter]
  DEDENT
  • Example
links:
    -> renderer
        model = com.github.lonelylockley.archinsight.model.remote.renderer.Source
        technology = HTTP, REST
        description = Renders DOT into requested image format
        call = /render/{format}, /render/svg/batch

4.3 ~> Asynchronous communication

  • Purpose: Represents an asynchronous interaction, such as message queue processing or event-based communication.
  • Usage: An asynchronous communication must be defined inside a links block. Each definition must reference either an identifier or an anonymous import statement. Additionally, it can be annotated with one or more annotations.
  • Syntax:
[@annotation]
~> <identifier> [from <identifier>]
  INDENT
    [model parameter]
    [technology parameter]
    [description parameter]
    [via parameter]
  DEDENT
  • Example:
links:
    ~> share
        model = com.github.lonelylockley.archinsight.events.FileChangeEvent
        technology = Kafka, Protobuf
        description = Notifies share service about file changes in repository
        via = kafka.topic.name

5. Imports

5.1 Named import

  • Purpose: Allows importing any number of context-level elements from other files. Once imported, these elements can be used inside links block to describe connections.
  • Usage: Named imports must be placed between the context declaration and the first entity (system or actor) inside the context. If a name of the imported element is already defined in current file, an alias may be set to the imported element. This alias then may be used as a regular identifier.
  • Syntax:
import <identifier> from context <identifier> [as <alias>]
  • Example: 
context archinsight

import google from context external_systems
import github from context external_systems as gh

5.2 Anonymous import

  • Purpose: Used to reference a container-level element (such as service or storage) from an already imported context-level element.
  • Usage: Anonymous imports replace an explicit identifier in a connection statement.
  • Syntax:
<identifier> from <identifier>
  • Example: 
links:
    -> auth from from google
    -> repository from gh

6. Annotations

Annotations provide meta-information to enrich the architecture model. Any entity (system, actor, service, storage, wire) may be annotated by one or more annotations.

  1. @attribute — Passes a comma-separated string of node or edge attributes directly to the Graphviz DOT engine, allowing full control over the visual representation of the annotated element. 
links:
    @attribute(style=dotted,arrowhead=diamond)
    -> target
        technology = HTTP, REST
  1. @planned — Marks an element as planned but not yet implemented.
@planned
system source
    name = Source system
  1. @deprecated — Marks an element as deprecated, indicating it should no longer be used.
links:
    @deprecated
    ~> source
        technology = Kafka, JSON

7. Comments

  • Purpose: Comments can be placed between any elements and are used for adding explanatory notes within the model.
  • Usage: A comment must be on a separate line. It starts with the # symbol and must follow the current indentation level.
  • Syntax:
# comment text
  • Example: 
# This is a comment at the root level
context example

# This is a comment inside a context block
system my_system
    name = System
    
    # Comment inside a system block
    service auth_service
        name = Auth

8. Notes

  • Purpose: A special type of comment that is displayed on the diagram as a yellow annotation box attached to the corresponding component
  • Usage: A note must appear on the same line as an element declaration. It is currently supported for system, actor, service, and storage elements.
  • Syntax:
system <identifier> # note text
actor <identifier> # note text
service <identifier> # note text
storage <identifier> # note text
  • Example: 
# This is a comment
system one  # This is a note
    name = The first system # This is a part of text value
Quick Navigation