archsight 0.3.2 → 0.4.0

data/lib/archsight/resources/technology_communication_network.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+# TechnologyCommunicationNetwork represents a logical network that connects nodes and system software
+class Archsight::Resources::TechnologyCommunicationNetwork < Archsight::Resources::Base
+  include_annotations :git, :architecture
+
+  description <<~MD
+    Represents a logical network: a management network, the public network, an overlay such as BGP-EVPN, a VPN or a
+    network that supports a metro region.
+
+    ## ArchiMate Definition
+
+    **Layer:** Technology
+    **Aspect:** Active Structure
+
+    A communication network is a set of structures and behaviors that connects devices or system software for
+    transmission, routing and reception of data.
+
+    ## Usage
+
+    Use TechnologyCommunicationNetwork to represent:
+
+    - Underlay networks (the routed fabric) and overlay networks that run on them (BGP-EVPN, VXLAN)
+    - Management, storage and public networks
+    - VPNs and mesh networks (one network with `network/topology: mesh`, not one element per pair of sites)
+    - Networks that support a metro region, made of the networks of its sites
+
+    Do not model a network per customer or tenant: the overlay is one network, its tenants are instances of it.
+    Physical links and fabrics are `TechnologyEquipment`.
+
+    ## Not this kind
+
+    - Cables, fibre routes and switch fabrics are `TechnologyEquipment`; the network is `realizedBy` them
+    - The routing or VPN software is `TechnologySystemSoftware` that realizes the network
+    - A network offered as a product to consumers can additionally be a `TechnologyService` realized by it
+    - No network per tenant, no element per pair of sites in a mesh
+
+    Which kind to pick: "Choosing the Kind: Infrastructure" in the modeling guide.
+
+    ## How it connects
+
+    - A network is `composedOf` other networks (a metro network of its site networks); the target must be a network
+      and the chain must not form a cycle
+    - A network `specializes` a more general network (the concept "management network" and its implementations)
+    - A network is `servedBy` the network it runs over: the underlay serves the overlay, a VPN is served by the
+      network it tunnels through
+    - A network is `locatedAt` the facilities and locations it spans, many of them for one network
+    - A network is `realizedBy` the `TechnologyEquipment` it runs over and the `TechnologySystemSoftware` that implements it
+      (the routing stack, the VPN software)
+    - An overlay that software builds is `realizedBy` that `ApplicationComponent` or `ApplicationService` (an SDN agent,
+      a network operator, a load-balancer controller), also when the software runs on the nodes the network serves
+    - A `TechnologyNode` is `servedBy` the networks it is attached to; the network page lists them
+    - A network is `realizedBy` the `TechnologyDevice`s that build it (its switches and routers) and `connects` the
+      devices attached to it (servers, firewalls, appliances). Both are written on the network, so a switch that is
+      also attached to the network it builds closes no cycle
+    - A network is `ownedBy` the team (`BusinessActor`) or `BusinessRole` that operates it
+  MD
+
+  icon "network"
+  layer "technology"
+
+  annotation "network/type",
+             description: "Role of the network",
+             title: "Network Type",
+             enum: %w[underlay overlay management public vpn other],
+             filter: :word,
+             summary: true
+
+  annotation "network/topology",
+             description: "Shape of the network",
+             title: "Topology",
+             enum: %w[mesh hub-and-spoke point-to-point ring other],
+             filter: :word,
+             summary: true
+
+  relation :composedOf, :technologyCommunicationNetworks, :TechnologyCommunicationNetwork
+  relation :specializes, :technologyCommunicationNetworks, :TechnologyCommunicationNetwork
+  relation :servedBy, :technologyCommunicationNetworks, :TechnologyCommunicationNetwork
+  relation :locatedAt, :technologyFacilities, :TechnologyFacility
+  relation :locatedAt, :locations, :Location
+  relation :realizedBy, :technologyEquipment, :TechnologyEquipment
+  relation :realizedBy, :technologyDevices, :TechnologyDevice
+  relation :connects, :technologyDevices, :TechnologyDevice
+  relation :realizedBy, :technologySystemSoftware, :TechnologySystemSoftware
+  relation :realizedBy, :applicationComponents, :ApplicationComponent
+  relation :realizedBy, :applicationServices, :ApplicationService
+  relation :ownedBy, :businessActors, :BusinessActor
+  relation :ownedBy, :businessRoles, :BusinessRole
+end

data/lib/archsight/resources/technology_device.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+# TechnologyDevice represents one physical machine: a server, switch, router, firewall or appliance
+class Archsight::Resources::TechnologyDevice < Archsight::Resources::Base
+  include_annotations :git, :architecture, :asset, :risk
+
+  description <<~MD
+    Represents one physical machine: a server, a switch, a router, a firewall, a terminal server or an appliance.
+
+    ## ArchiMate Definition
+
+    **Layer:** Technology
+    **Aspect:** Active Structure
+
+    A device is a physical IT resource upon which system software and artifacts may be stored or deployed for
+    execution. It is a specialization of a node.
+
+    ## Usage
+
+    Use TechnologyDevice when the individual machine matters: which room it stands in, which switch it is cabled to,
+    which machines a failure domain loses.
+
+    - One element per physical machine (name it after the host: "Device:Frankfurt:Server01")
+    - A group of machines with one role ("the hypervisors of the platform") stays a logical `TechnologyNode` that is
+      `realizedBy` its devices
+    - A virtual chassis, a stack or a cluster pair is a device `composedOf` its member devices
+
+    ## Not this kind
+
+    - A VM, a Kubernetes node or a host role is a `TechnologyNode`
+    - A rack, a fabric or a link between sites is `TechnologyEquipment` (a rack is `composedOf` its devices)
+    - The network a switch builds is a `TechnologyCommunicationNetwork` `realizedBy` the switch
+
+    Which kind to pick: "Choosing the Kind: Infrastructure" in the modeling guide.
+
+    ## How it connects
+
+    - A device is `locatedAt` the `TechnologyFacility` it stands in, usually a room (`facility/type: room`)
+    - A device is `connectedTo` the devices it is cabled to (ArchiMate association). The cable is declared once, on
+      one of the two devices; the other shows it as incoming. Cabling is cyclic by nature and stays out of the
+      cycle check
+    - A device is `composedOf` its members (virtual chassis, stack)
+    - A `TechnologyNode` is `realizedBy` the devices it consists of
+    - A `TechnologyCommunicationNetwork` is `realizedBy` its switches and routers and `connects` the devices attached
+      to it
+    - `TechnologyEquipment` (a rack, a delivered hardware block) is `composedOf` its devices
+    - A device is `ownedBy` the team (`BusinessActor`) or `BusinessRole` responsible for operating it and `servedBy`
+      the team it is dedicated to (ArchiMate serving: a test server held by one team); `device/purpose` says what for
+
+    A device points to nothing above it: nodes, networks and equipment point down to the device, and the teams it
+    points to point to nothing further, so the relations stay free of cycles.
+  MD
+
+  icon "server"
+  layer "technology"
+
+  annotation "device/type",
+             description: "Kind of device",
+             title: "Device Type",
+             enum: %w[server switch router firewall terminal-server appliance other],
+             filter: :word,
+             summary: true
+  annotation "device/role",
+             description: "What the device does, e.g. hypervisor, storage, leaf, spine, core, management",
+             title: "Role",
+             filter: :word,
+             summary: true
+  annotation "device/model",
+             description: "Vendor and model",
+             title: "Model"
+  annotation "device/serial",
+             description: "Serial number",
+             title: "Serial"
+  annotation "device/rack",
+             description: "Rack and height units, e.g. B12 U20-21",
+             title: "Rack"
+  annotation "device/purpose",
+             description: "What the device is dedicated to, e.g. kernel regression tests",
+             title: "Purpose",
+             filter: :word
+
+  relation :locatedAt, :technologyFacilities, :TechnologyFacility
+  relation :connectedTo, :technologyDevices, :TechnologyDevice
+  relation :composedOf, :technologyDevices, :TechnologyDevice
+  relation :ownedBy, :businessActors, :BusinessActor
+  relation :ownedBy, :businessRoles, :BusinessRole
+  relation :servedBy, :businessActors, :BusinessActor
+end

data/lib/archsight/resources/technology_equipment.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+# TechnologyEquipment represents racks, fabrics and physical clusters inside a facility
+class Archsight::Resources::TechnologyEquipment < Archsight::Resources::Base
+  include_annotations :git, :architecture
+
+  description <<~MD
+    Represents physical equipment inside a facility: racks, network fabrics, physical clusters.
+
+    ## ArchiMate Definition
+
+    **Layer:** Technology (physical element)
+    **Aspect:** Active Structure
+
+    TechnologyEquipment is one or more physical machines, tools or instruments that can create, use, store, move or transform
+    materials.
+
+    ## Usage
+
+    Use TechnologyEquipment to represent:
+
+    - Racks and rack rows
+    - Network fabrics and switch stacks
+    - Physical clusters (storage arrays, hardware pools) that technology nodes run on
+    - Links between facilities (fibre routes, carrier circuits, `equipment/type: link`) and backbones made of them
+
+    Model individual physical machines as `TechnologyDevice` and VMs as `TechnologyNode`; use TechnologyEquipment only
+    when the physical grouping matters.
+
+    ## Not this kind
+
+    - A single physical machine (server, switch, router, appliance) is a `TechnologyDevice`; a VM or host role is a
+      `TechnologyNode`
+    - The network that runs over the links is a `TechnologyCommunicationNetwork` `realizedBy` the equipment
+    - A link is one element `locatedAt` its two facilities, not a `TechnologyService`
+
+    Which kind to pick: "Choosing the Kind: Infrastructure" in the modeling guide.
+
+    ## How it connects
+
+    - TechnologyEquipment is `locatedAt` the facilities it stands in. A link between facilities is one TechnologyEquipment that is
+      `locatedAt` both end facilities
+    - TechnologyEquipment is `composedOf` other TechnologyEquipment (a backbone of its links; the chain must not form a
+      cycle) and of the `TechnologyDevice`s it holds (a rack, a delivered hardware block)
+    - A technology service or node is `realizedBy` the TechnologyEquipment it runs on or over (a network service by the link)
+    - TechnologyEquipment is optional: nodes and services can be `locatedAt` a facility directly
+    - TechnologyEquipment is `ownedBy` the team (`BusinessActor`) or `BusinessRole` responsible for operating it and
+      `servedBy` the team it is dedicated to (a partition of a shared test cluster); `equipment/purpose` says what for.
+      The devices of a partition are normally served by the same team; `archsight lint` warns when one is not
+    - A `BusinessContract` `covers` the equipment it obliges the provider to deliver, and the `ImplementationWorkPackage` that
+      installs or changes it `affects` it
+  MD
+
+  icon "cpu"
+  layer "technology"
+
+  annotation "equipment/type",
+             description: "Kind of equipment",
+             title: "TechnologyEquipment Type",
+             enum: %w[rack network-fabric link cluster storage power cooling other],
+             filter: :word,
+             summary: true
+
+  annotation "equipment/purpose",
+             description: "What the equipment is dedicated to, e.g. hypervisor regression tests",
+             title: "Purpose",
+             filter: :word
+
+  relation :locatedAt, :technologyFacilities, :TechnologyFacility
+  relation :composedOf, :technologyEquipment, :TechnologyEquipment
+  relation :composedOf, :technologyDevices, :TechnologyDevice
+  relation :ownedBy, :businessActors, :BusinessActor
+  relation :ownedBy, :businessRoles, :BusinessRole
+  relation :servedBy, :businessActors, :BusinessActor
+end

data/lib/archsight/resources/technology_event.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+# TechnologyEvent represents a technology event: something that happens in the infrastructure and triggers or interrupts technology behavior
+class Archsight::Resources::TechnologyEvent < Archsight::Resources::Base
+  include_annotations :git, :architecture, :risk
+
+  description <<~MD
+    Represents a technology event: something that happens in the infrastructure and triggers or interrupts technology behavior.
+
+    ## ArchiMate Definition
+
+    **Layer:** Technology
+    **Aspect:** Behavior
+
+    An event is something that happens and influences behavior. It does not last: it triggers or interrupts
+    processes and services. In the risk and security overlay of the Open Group paper (*Modeling Enterprise Risk
+    Management and Security with the ArchiMate Language*) a threat event and a loss event are events that carry a
+    type; set `event/type` to say which.
+
+    ## Usage
+
+    Use TechnologyEvent for events on the technology level:
+
+    - Threat events and loss events of the infrastructure (a host compromise, an outage, a failed disk)
+    - Findings of a scan or a penetration test on a host or network
+    - Infrastructure alerts and changes
+
+    ## Event types
+
+    - `threat-event`: an event with the potential to harm an asset; it can trigger a loss event
+    - `attack`: a threat event caused by intentional malicious activity
+    - `loss-event`: an event that harms an asset (a hazard materialises, a vulnerability is exploited)
+    - `incident`: a loss event that has happened
+    - `opportunity-event`: an event that can add value
+    - `audit`, `scan`, `change`: events that produce assessments or alter the architecture
+    - `other`
+
+    Filter, group and query by `event/type`, `risk/domain` and `risk/category` to see, for example, every loss
+    event of a risk domain.
+
+    ## How it connects
+
+    - A threat event `triggers` a loss event or a process or service; threat and loss events may sit on different
+      layers (a technology event triggers an application or business event)
+    - `causedBy` the threat agent (an actor, component or node)
+    - `affects` the assets it harms
+    - A `MotivationDriver` (the threat) `triggers` it; a vulnerability `MotivationAssessment` `influences` it
+  MD
+
+  icon "warning-triangle"
+  layer "technology"
+
+  annotation "event/type",
+             description: "What kind of event this is (specialization of the event, see the risk and security overlay)",
+             enum: %w[threat-event attack loss-event incident opportunity-event audit scan change other],
+             filter: :word,
+             summary: true
+
+  annotation "event/severity",
+             description: "Severity of the event",
+             enum: %w[info low medium high critical],
+             filter: :word,
+             summary: true
+
+  annotation "event/occurred",
+             description: "When the event happened or is expected (ISO 8601 date or time)",
+             title: "Occurred",
+             validator: ->(value) { Archsight::Resources::Page.timestamp_error(value) }
+
+  relation :triggers, :technologyServices, :TechnologyService
+  relation :triggers, :technologyEvents, :TechnologyEvent
+  relation :triggers, :applicationEvents, :ApplicationEvent
+  relation :triggers, :businessEvents, :BusinessEvent
+  relation :causedBy, :businessActors, :BusinessActor
+  relation :causedBy, :applicationComponents, :ApplicationComponent
+  relation :causedBy, :technologyNodes, :TechnologyNode
+  relation :affects, :technologyNodes, :TechnologyNode
+  relation :affects, :technologyServices, :TechnologyService
+  relation :affects, :technologySystemSoftwares, :TechnologySystemSoftware
+end

data/lib/archsight/resources/technology_facility.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+# TechnologyFacility represents a building, data center or site
+class Archsight::Resources::TechnologyFacility < Archsight::Resources::Base
+  include_annotations :git, :architecture
+
+  description <<~MD
+    Represents a physical structure where technology runs: a building, data center or other site.
+
+    ## ArchiMate Definition
+
+    **Layer:** Technology (physical element)
+    **Aspect:** Active Structure
+
+    A facility is a physical structure or environment. Technology nodes, services and system software are located
+    at facilities, and facilities themselves are located at a place.
+
+    ## Usage
+
+    Use TechnologyFacility to represent:
+
+    - Data centers and colocation sites
+    - Offices
+    - Edge sites
+    - Parts of a site (campus, building, hall), nested with `composedOf`
+    - Rooms: a server room or fire compartment (`facility/type: room`) the data center is `composedOf`; devices stand
+      in it, which makes it a failure domain
+
+    ## Not this kind
+
+    - A country, metro or region is a `Location`
+    - A rack, cage or fabric inside the site is `TechnologyEquipment`; a server is a `TechnologyDevice` (or a logical
+      `TechnologyNode`) `locatedAt` the facility
+    - A data center is never a `TechnologyNode` and never an annotation on other elements
+
+    Which kind to pick: "Choosing the Kind: Infrastructure" in the modeling guide.
+
+    ## How it connects
+
+    - Things that run at a facility point to it with `locatedAt`: `TechnologyNode`, `TechnologyService`,
+      `TechnologySystemSoftware`, `TechnologyEquipment` and `TechnologyDevice`. One element can be located at many
+      facilities (one cluster that runs in three data centers is one element with three relations, not three copies)
+    - A facility is `locatedAt` a `Location` and `composedOf` other facilities (campus, hall, room)
+    - A facility is `servedBy` the `BusinessActor` that operates it
+    - The facility page lists what is located there (incoming `locatedAt`), grouped by kind
+
+    A service that runs on different platforms in different facilities is not given a qualifier: the nodes of the
+    platform are `locatedAt` the same facilities, so the pair is derivable.
+  MD
+
+  icon "building"
+  layer "technology"
+
+  annotation "facility/type",
+             description: "Kind of site",
+             title: "TechnologyFacility Type",
+             enum: %w[data-center colocation office edge room],
+             filter: :word,
+             summary: true
+
+  annotation "facility/stage",
+             description: "Free text stage of the facility (planned, in build, productive, phase-out, ...)",
+             title: "Stage",
+             filter: :word,
+             summary: true
+
+  relation :locatedAt, :locations, :Location
+  relation :composedOf, :technologyFacilities, :TechnologyFacility
+  relation :servedBy, :businessActors, :BusinessActor
+end

data/lib/archsight/resources/technology_node.rb

@@ -2,7 +2,7 @@
 
 # TechnologyNode represents physical infrastructure (VMs, servers, Kubernetes nodes)
 class Archsight::Resources::TechnologyNode < Archsight::Resources::Base
-  include_annotations :git, :architecture
+  include_annotations :git, :architecture, :asset, :risk
 
   description <<~MD
     Represents physical infrastructure hosting application components.
@@ -25,6 +25,53 @@ class Archsight::Resources::TechnologyNode < Archsight::Resources::Base
     - Kubernetes nodes
     - Network appliances
     - Storage arrays
+
+    ## Not this kind
+
+    - A building or data center is a `TechnologyFacility`; a rack or fabric is `TechnologyEquipment`
+    - Software running on the node (database, routing stack) is `TechnologySystemSoftware`
+    - One node per host role is often enough; many identical hosts are one node `locatedAt` several facilities
+    - A single physical machine whose room or cabling matters is a `TechnologyDevice`; the node is `realizedBy` it
+
+    Which kind to pick: "Choosing the Kind: Infrastructure" in the modeling guide.
+
+    ## Location
+
+    A node is `locatedAt` the `TechnologyFacility` (or facilities) it stands in; see `TechnologyFacility`.
+
+    ## Networks
+
+    A node is `servedBy` the `TechnologyCommunicationNetwork`s it is attached to (management, public, an overlay).
+
+    ## Teams
+
+    A node is `ownedBy` the team (`BusinessActor`) or `BusinessRole` that operates it and `servedBy` the team it is
+    dedicated to (a test cluster held by one team).
+
+    ## Physical realization
+
+    A node is `realizedBy` the `TechnologyEquipment` it consists of or stands on (a router on its rack); see `TechnologyEquipment`.
+    A logical node (a host role, "the hypervisors of the platform") is `realizedBy` the `TechnologyDevice`s, the
+    physical machines, that make it up.
+
+    ## Concept and implementation
+
+    A node can `specialize` another node (ArchiMate specialization): the general node is the concept (a regional
+    cluster), the specific nodes are its implementations. The concept's page lists them as incoming "specializes".
+    A node made of other nodes (a cluster of hosts) is `composedOf` them (ArchiMate composition). Both only point at
+    nodes, and neither may form a cycle.
+
+    ## Deployment
+
+    A node `assignedTo` the artifacts that are deployed on it (ArchiMate assignment): the image it boots, the
+    packages installed on it. The relation is written on the node, which owns the deployment; the artifact's page
+    shows the nodes as incoming "deployed on".
+
+    ## Security and risk modelling
+
+    A node is the typical asset of a vulnerability assessment: a scan result is a `MotivationAssessment` of type
+    `vulnerability` that `assesses` the nodes it was found on (one vulnerability, many nodes) and `influences` the
+    loss events it makes possible. Set the `asset/*` profile and `risk/domain` to group nodes by context.
   MD
 
   icon "server-connection"
@@ -38,5 +85,14 @@ class Archsight::Resources::TechnologyNode < Archsight::Resources::Base
 
   relation :realizes, :motivationConstraints, :MotivationConstraint
   relation :servedBy, :technologyServices, :TechnologyService
+  relation :servedBy, :technologyCommunicationNetworks, :TechnologyCommunicationNetwork
   relation :servedBy, :businessActors, :BusinessActor
+  relation :ownedBy, :businessActors, :BusinessActor
+  relation :ownedBy, :businessRoles, :BusinessRole
+  relation :locatedAt, :technologyFacilities, :TechnologyFacility
+  relation :realizedBy, :technologyEquipment, :TechnologyEquipment
+  relation :realizedBy, :technologyDevices, :TechnologyDevice
+  relation :specializes, :technologyNodes, :TechnologyNode
+  relation :composedOf, :technologyNodes, :TechnologyNode
+  relation :assignedTo, :technologyArtifacts, :TechnologyArtifact
 end

data/lib/archsight/resources/technology_service.rb

@@ -25,6 +25,36 @@ class Archsight::Resources::TechnologyService < Archsight::Resources::Base
     - Managed database services
     - CI/CD pipeline services
     - Monitoring and logging platforms
+
+    ## Not this kind
+
+    - The software that provides it is `TechnologySystemSoftware`, the machines are `TechnologyNode`s
+    - A network is a `TechnologyCommunicationNetwork`; a physical link is `TechnologyEquipment`
+    - One service for all sites, `locatedAt` each `TechnologyFacility`, not a copy per site
+
+    Which kind to pick: "Choosing the Kind: Infrastructure" in the modeling guide.
+
+    ## Location
+
+    A service that runs in several data centers is one service that is `locatedAt` each `TechnologyFacility`, not one service
+    per site.
+
+    ## Physical realization
+
+    A service is `realizedBy` the `TechnologyEquipment` it runs over: a backbone network service is realized by the links
+    between the facilities (`equipment/type: link`).
+
+      ## Deployed components
+
+    Application components deployed on the service point to it with `servedBy`; they are listed as incoming
+    "servedBy" from ApplicationComponent on its page. An ApplicationService that is `servedBy` the service uses it as a
+    whole; list a cluster there only when the service's own components run in it.
+
+    ## Concept and implementation
+
+    A service can `specialize` another service (ArchiMate specialization): the general service is the concept, the
+    specific ones are its implementations, listed as incoming "specializes" on the concept's page. The target must be
+    a TechnologyService and the chain must not form a cycle.
   MD
 
   icon "cloud"
@@ -36,7 +66,10 @@ class Archsight::Resources::TechnologyService < Archsight::Resources::Base
              format: :markdown
 
   relation :suppliedBy, :technologyComponents, :TechnologySystemSoftware
+  relation :specializes, :technologyServices, :TechnologyService
   relation :servedBy, :businessActors, :BusinessActor
+  relation :locatedAt, :technologyFacilities, :TechnologyFacility
+  relation :realizedBy, :technologyEquipment, :TechnologyEquipment
   relation :realizes, :motivationRequirements, :MotivationRequirement
   relation :partiallyRealizes, :motivationRequirements, :MotivationRequirement
   relation :plans, :motivationRequirements, :MotivationRequirement

data/lib/archsight/resources/technology_system_software.rb

@@ -25,12 +25,39 @@ class Archsight::Resources::TechnologySystemSoftware < Archsight::Resources::Bas
     - Cache clusters
     - Load balancers
     - Service meshes
+
+    ## Not this kind
+
+    - The machine it runs on is a `TechnologyNode`
+    - What consumers use from it is a `TechnologyService`
+    - A routing stack that implements a network realizes a `TechnologyCommunicationNetwork`
+
+    Which kind to pick: "Choosing the Kind: Infrastructure" in the modeling guide.
+
+    ## Location
+
+    System software is `locatedAt` the `TechnologyFacility` (or facilities) it runs in.
+
+    ## Deployment
+
+    System software `assignedTo` the artifacts it executes (ArchiMate assignment), written on the system software.
+    The artifact's page shows it as incoming "deployed on".
+
+    ## Concept and implementation
+
+    System software can `specialize` other system software (ArchiMate specialization): the general one is the
+    concept, the specific ones are its implementations, listed as incoming "specializes" on the concept's page.
+    A platform that bundles components is `composedOf` them (ArchiMate composition). Both only point at system
+    software, and neither may form a cycle.
   MD
 
   icon "terminal-tag"
   layer "technology"
 
   relation :realizedBy, :technologyComponents, :TechnologyNode
+  relation :specializes, :technologySystemSoftware, :TechnologySystemSoftware
+  relation :composedOf, :technologySystemSoftware, :TechnologySystemSoftware
+  relation :assignedTo, :technologyArtifacts, :TechnologyArtifact
   relation :realizedThrough, :technologyArtifacts, :TechnologyArtifact
   relation :exposes, :applicationInterfaces, :ApplicationInterface
   relation :dependsOn, :applicationInterfaces, :ApplicationInterface
@@ -38,4 +65,5 @@ class Archsight::Resources::TechnologySystemSoftware < Archsight::Resources::Bas
   relation :partiallyRealizes, :motivationRequirements, :MotivationRequirement
   relation :plans, :motivationRequirements, :MotivationRequirement
   relation :evidencedBy, :complianceEvidences, :ComplianceEvidence
+  relation :locatedAt, :technologyFacilities, :TechnologyFacility
 end

data/lib/archsight/resources.rb

@@ -14,6 +14,12 @@ module Archsight
       "BusinessConstraint" => "MotivationConstraint"
     }.freeze
 
+    # Annotations that were renamed: the old key is rewritten to the new one when a document is loaded (see
+    # Database#accept_old_names) and reported as deprecated by `archsight lint`.
+    ANNOTATION_ALIASES = {
+      "page/confluence" => "link/confluence"
+    }.freeze
+
     # Relation keys (the plural kind names under `spec.<verb>`) that were renamed together with their kind
     RELATION_KEY_ALIASES = {
       "businessRequirements" => "motivationRequirements",
@@ -28,6 +34,12 @@ module Archsight
     DERIVED_VERBS = %i[mentions depicts].freeze
     DERIVED_KEY = :resources
 
+    # The layers a kind belongs to (Base.layer), top to bottom: why (motivation), what we want to become (strategy),
+    # how the change happens (implementation and migration), then the architecture it changes (business, application,
+    # technology). `other` holds the tool's own kinds (pages, views, imports, ...) and stays last. Everything that
+    # lists or orders layers uses this; the frontend repeats it in frontend/src/composables/useLayers.js.
+    LAYERS = %w[motivation strategy implementation business application technology other].freeze
+
     # The derived relations of every class, next to the ones it declares: [verb, key, kind]
     DERIVED_RELATIONS = DERIVED_VERBS.map { |verb| [verb, DERIVED_KEY, "Resource"] }.freeze
 

data/lib/archsight/version.rb

@@ -4,5 +4,5 @@
 # Do not edit manually.
 
 module Archsight
-  VERSION = "0.3.2"
+  VERSION = "0.4.0"
 end

data/lib/archsight/web/api/analysis_helpers.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Archsight; end
+module Archsight::Web; end
+module Archsight::Web::API; end
+
+# JSON of `POST /api/v1/kinds/Analysis/instances/:name/execute`: the result and its sections
+module Archsight::Web::API::AnalysisHelpers
+  def build_analysis_result(result)
+    data = {
+      name: result.name,
+      success: result.success?,
+      has_findings: result.has_findings?,
+      duration: result.duration,
+      sections: result.sections.map { |s| serialize_analysis_section(s) }
+    }
+
+    if result.failed?
+      data[:error] = result.error
+      data[:error_backtrace] = result.error_backtrace if result.error_backtrace&.any?
+    end
+
+    data
+  end
+
+  def serialize_analysis_section(section)
+    case section[:type]
+    when :heading
+      { type: "heading", level: section[:level], text: section[:text] }
+    when :text
+      { type: "text", content: markdown(section[:content]) }
+    # the *_html fields: the values as inline markdown with [[Kind/Name]] links, next to the raw values
+    when :message
+      { type: "message", level: section[:level].to_s, message: section[:message],
+        message_html: analysis_html(section[:message]) }
+    when :table
+      { type: "table", headers: section[:headers], rows: section[:rows],
+        rows_html: section[:rows].map { |row| row.map { |cell| analysis_html(cell) } } }
+    when :list
+      { type: "list", items: section[:items], items_html: section[:items].map { |item| analysis_html(item) } }
+    when :code
+      { type: "code", lang: section[:lang], content: section[:content] }
+    else
+      { type: section[:type].to_s }
+    end
+  end
+
+  # A value of a table cell, list item or message as html: HTML in it stays text (escaped first) except a line
+  # break (`<br>` or a newline, the usual way to break a line in a table cell), markdown and [[Kind/Name]] links are
+  # rendered; a value without markup is only escaped, so large tables stay cheap
+  def analysis_html(value)
+    escaped = Rack::Utils.escape_html(value.to_s).gsub(%r{&lt;br\s*/?&gt;}i, "<br>").gsub(/\r?\n/, "<br>")
+    escaped.match?(/[*_`\[{]|https?:/) ? inline_markdown(escaped) : escaped
+  end
+end