archsight 0.3.3 → 0.4.0

data/lib/archsight/resources/location.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+# Location represents a geographic or conceptual place
+class Archsight::Resources::Location < Archsight::Resources::Base
+  include_annotations :git, :architecture
+
+  description <<~MD
+    Represents a place: a country, a metro area, a region or any other geographic or conceptual position.
+
+    ## ArchiMate Definition
+
+    **Layer:** Other (ArchiMate: composite element)
+    **Aspect:** Composite
+
+    A location is a conceptual or physical place or position where concepts are located (structure elements)
+    or performed (behavior elements). In archsight it is the coarse place that facilities sit in.
+
+    ## Usage
+
+    Use Location to represent:
+
+    - Countries and regions (Germany, EU)
+    - Metro areas and cities (Frankfurt)
+    - Conceptual places (a cloud region, a jurisdiction)
+
+    ## Not this kind
+
+    - A building, campus or hall is a `TechnologyFacility` that is `locatedAt` the location
+    - A cloud region that is really a set of data centers: a location, with the data centers as facilities in it
+
+    Which kind to pick: "Choosing the Kind: Infrastructure" in the modeling guide.
+
+    ## How it connects
+
+    - A `TechnologyFacility` is `locatedAt` a location (many facilities, one location)
+    - Everything located at a facility of the location is found through the facility; the location page lists the
+      facilities that are located there, grouped by kind
+
+    Model the sites themselves as `TechnologyFacility`, not as locations: a data center is a physical structure.
+  MD
+
+  icon "map-pin"
+  layer "other"
+
+  annotation "location/country",
+             description: "Country of the location (name or ISO 3166 code)",
+             title: "Country",
+             filter: :word,
+             summary: true
+
+  annotation "location/city",
+             description: "City or metro area of the location",
+             title: "City",
+             filter: :word,
+             summary: true
+end

data/lib/archsight/resources/motivation_requirement.rb

@@ -36,6 +36,12 @@ class Archsight::Resources::MotivationRequirement < Archsight::Resources::Base
 
     Both show as incoming relations on the requirement's page.
 
+    ## Where it comes from
+
+    The source of a requirement is the `MotivationStakeholder` that `hasConcern` for it, directly or through the goal
+    the requirement answers. The stakeholder is `representedBy` the actor or role behind it, so the chain reaches the
+    actual organisation that asked for the requirement.
+
     ## Security and risk modelling
 
     - **Control measure:** `requirement/type` `control-measure` is a measure that a control objective

data/lib/archsight/resources/motivation_stakeholder.rb

@@ -27,6 +27,18 @@ class Archsight::Resources::MotivationStakeholder < Archsight::Resources::Base
     - Regulatory bodies
     - Technical leadership
 
+    ## How it connects
+
+    - It `hasConcern` for the capabilities, goals, drivers, assessments, constraints and requirements it cares about.
+      That makes it the **source** of those requirements: the requirement's page shows the stakeholder as incoming.
+    - It is `representedBy` the `BusinessActor` (the actual organisation or person, e.g. the customer organisation,
+      not "customer") or `BusinessRole` that holds this interest. A stakeholder is a role; the actor is the party
+      behind it.
+
+    In ArchiMate a stakeholder is associated with the business actor or role that plays it; in TOGAF the stakeholder
+    map of Phase A links stakeholders and their concerns to organisation units and actors, and the requirements
+    repository records each requirement's source.
+
     ## Security and risk modelling
 
     A stakeholder (CISO, risk committee, data protection officer) can `hasConcern` for threats
@@ -42,4 +54,6 @@ class Archsight::Resources::MotivationStakeholder < Archsight::Resources::Base
   relation :hasConcern, :goals, :MotivationGoal
   relation :hasConcern, :motivationDrivers, :MotivationDriver
   relation :hasConcern, :motivationAssessments, :MotivationAssessment
+  relation :representedBy, :businessActors, :BusinessActor
+  relation :representedBy, :businessRoles, :BusinessRole
 end

data/lib/archsight/resources/page.rb

@@ -6,6 +6,8 @@ require "time"
 # Page is a wiki page authored as a markdown file with YAML frontmatter.
 # It is sourced by Archsight::PageLoader and arranged in a tree by PageMenu.
 class Archsight::Resources::Page < Archsight::Resources::Base
+  include_annotations :links
+
   description <<~MD
     Represents a wiki page authored as a markdown file with YAML frontmatter.
 
@@ -18,8 +20,8 @@ class Archsight::Resources::Page < Archsight::Resources::Base
 
     ## Frontmatter
 
-    `title`, `author`, `owner`, `status`, `tags` (comma-separated), `toc` (yes/no), `confluence`
-    (URL of the linked Confluence page) and an optional `name` (defaults to the file path).
+    `title`, `author`, `owner`, `status`, `tags` (comma-separated), `toc` (yes/no), `links` (a mapping of
+    names to URLs, e.g. `confluence`, `jira`) and an optional `name` (defaults to the file path).
 
     ## Security and risk modelling
 
@@ -59,11 +61,6 @@ class Archsight::Resources::Page < Archsight::Resources::Base
              title: "Table of Contents",
              enum: %w[yes no],
              sidebar: false
-  annotation "page/confluence",
-             description: "URL of the corresponding Confluence page (used for a later export)",
-             title: "Confluence",
-             type: URI,
-             sidebar: false
   annotation "page/created",
              description: "When the page was created (ISO 8601 date or time)",
              title: "Created",

data/lib/archsight/resources/strategy_capability.rb

@@ -25,6 +25,15 @@ class Archsight::Resources::StrategyCapability < Archsight::Resources::Base
     - Organizational abilities
     - Core competencies
     - Value-generating functions
+
+    ## Choosing this kind
+
+    **Question:** What must the organization be *able* to do?
+    **Test:** It survives swapping product, team and technology. It is not a certificate or a quality.
+    **Name:** An ability noun phrase ("Payment Processing"), never a product, team or technology.
+
+    A product `realizes` the capability. Only internal capabilities that no product carries are `servedBy` a service.
+    See the modeling guide, "Choosing the Kind".
   MD
 
   icon "strategy"

data/lib/archsight/resources/technology_artifact.rb

@@ -27,6 +27,15 @@ class Archsight::Resources::TechnologyArtifact < Archsight::Resources::Base
     - Container images
     - Build artifacts
     - Configuration packages
+    - Images (OS, VM template, disk or boot image, `artifact/type: image`)
+
+    ## Contents and deployment
+
+    An artifact that contains other artifacts `aggregates` them (ArchiMate aggregation): an image contains packages,
+    a chart references container images. A node or system software that runs an artifact `assignedTo` it (ArchiMate
+    assignment, written on the node). The artifact's page shows both as incoming relations ("contained in" and
+    "deployed on"). `ApplicationComponent realizedThrough TechnologyArtifact` says what a component is built from,
+    not where the artifact runs.
   MD
 
   icon "puzzle"
@@ -36,12 +45,9 @@ class Archsight::Resources::TechnologyArtifact < Archsight::Resources::Base
   annotation "artifact/type",
              description: "Type of technology artifact",
              title: "Artifact Type",
-             enum: %w[repo container chart deb rpm]
+             enum: %w[repo container chart deb rpm image binary archive]
 
   # Dynamic annotations (patterns with *)
-  annotation "link/*",
-             description: "Documentation and resource links",
-             sidebar: false
   annotation "scc/language/*/loc",
              description: "Lines of code per programming language",
              sidebar: false
@@ -240,6 +246,7 @@ class Archsight::Resources::TechnologyArtifact < Archsight::Resources::Base
   end
 
   relation :servedBy, :technologyComponents, :TechnologyArtifact
+  relation :aggregates, :technologyArtifacts, :TechnologyArtifact
   relation :suppliedBy, :technologyComponents, :TechnologyService
   relation :maintainedBy, :businessActors, :BusinessActor
   relation :contributedBy, :businessActors, :BusinessActor

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_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

@@ -26,6 +26,47 @@ class Archsight::Resources::TechnologyNode < Archsight::Resources::Base
     - 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
@@ -44,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