Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 4 additions & 3 deletions docs/archimate.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,8 +44,8 @@ ArchiMate is an open and independent enterprise architecture modeling language d
| Relationship | Supported as |
|--------------|--------------|
| **Specialization** | `specializes` between technology elements of one kind (node, system software, service), see "Concept and Implementation" in the modeling guide |
| **Composition** | `composedOf` between nodes and between system software |
| **Aggregation** | `aggregates` between technology artifacts (an image contains packages), see "Deployment" in the modeling guide |
| **Composition** | `composedOf` between nodes and between system software; from a `Grouping` to resources of any kind |
| **Aggregation** | `aggregates` between technology artifacts (an image contains packages), see "Deployment" in the modeling guide; from a `Grouping` to resources of any kind |
| **Assignment** | `assignedTo` from a node or system software to the technology artifacts deployed on it |

### Relationship Connectors
Expand Down Expand Up @@ -198,7 +198,8 @@ call-offs, SLAs and amendments, `stipulates` the requirements and constraints it
| **Grouping** | Aggregates or composes concepts that belong together based on some common characteristic. |
| **Location** | A conceptual or physical place or position where concepts are located (structure elements) or performed (behavior elements). |

**Supported in archsight:** Location (`Location`) is modelled and shown under Other. Grouping is not.
**Supported in archsight:** Location (`Location`) and Grouping (`Grouping`) are modelled and shown under Other. A
grouping aggregates or composes resources of every kind, groupings included, see "Grouping" in the modeling guide.

## ArchiMate Layers

Expand Down
1 change: 1 addition & 0 deletions docs/icons.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,7 @@ Current icon assignments for each resource type:
| TechnologyDevice | `server` | <i class="iconoir-server"></i> |
| TechnologyFacility | `building` | <i class="iconoir-building"></i> |
| Location | `map-pin` | <i class="iconoir-map-pin"></i> |
| Grouping | `square-dashed` | <i class="iconoir-square-dashed"></i> |
| TechnologyNode | `server-connection` | <i class="iconoir-server-connection"></i> |
| StrategyCapability | `strategy` | <i class="iconoir-strategy"></i> |
| TechnologyArtifact | `puzzle` | <i class="iconoir-puzzle"></i> |
Expand Down
1 change: 1 addition & 0 deletions docs/index.md.erb
Original file line number Diff line number Diff line change
Expand Up @@ -93,6 +93,7 @@ Resources representing technology infrastructure and artifacts.
### Other

- [ComplianceEvidence](/doc/resources/compliance_evidence) - Evidence for compliance requirements
- [Grouping](/doc/resources/grouping) - Domains, scopes and families of resources of any kind
- [Location](/doc/resources/location) - Countries, metros, regions and other places
- [View](/doc/resources/view) - Saved queries and custom views

Expand Down
36 changes: 34 additions & 2 deletions docs/modeling.md
Original file line number Diff line number Diff line change
Expand Up @@ -936,9 +936,10 @@ How to model it:
- **Vulnerability scan.** One `MotivationAssessment` of type `vulnerability` per finding, `assesses` every node it was
found on, `influences` the loss events and risks it makes possible. Business impact follows from the model: the node
serves services, services serve processes.
- **Grouping (risk domains).** ArchiMate has no domain element; set `risk/domain` (and `risk/category`: hazard,
- **Risk domains.** Set `risk/domain` (and `risk/category`: hazard,
financial, operational, strategic, compliance, security) on events, assessments, drivers, requirements, controls and
assets, and query or build a `View` per domain to see its threats, risks, measures and assets together.
assets, and query or build a `View` per domain to see its threats, risks, measures and assets together. A `Grouping`
is only worth it when the domain itself has an owner, a description or members that share no annotation.
- **Policies.** The text of a policy is a `Page`; the structured statement (owner, validity, status, framework) is a
`MotivationPrinciple` that links to the page with `[[Page]]`.
- **Initial and residual risk.** Record both on the assessment (`risk/initial-*`, `risk/residual-*`) and the decision
Expand Down Expand Up @@ -975,6 +976,37 @@ A ComplianceEvidence answers "how is the requirement met" in structured markdown
`evidence/verification`, `evidence/gaps` and `evidence/sources`. Because they are separate annotations they can be
queried, for example `ComplianceEvidence: evidence/gaps =~ "needs review"`.

### Grouping

A `Grouping` gathers resources that belong together by a criterion that is not a place: a domain, the scope of a
programme or review, a product family that spans layers. It holds resources of every kind, other groupings included, so
groups nest. The members are listed on the grouping only, one key per kind under one of two verbs:

| Verb | Means | Example |
|------|-------|---------|
| `aggregates` | the member belongs to the group and stands on its own; it can be in several groups | a shared service in two domains |
| `composedOf` | the member is a part of this whole and of no other | the components that exist only for the domain |

```yaml
kind: Grouping
metadata:
name: Domain:Payments
spec:
aggregates:
strategyCapabilities: [Payment Processing]
groupings: [Domain:Payments:Refunds]
composedOf:
applicationComponents: [Payments:API, CardVault:API]
```

A member's page lists its groups under Relations, and the MCP `summary` names them ("Groups" or "Part of"). Queries
follow membership like any relation: `ApplicationComponent: <- Grouping` (in some group), `Grouping: -> "Payments:API"`.
A grouping that contains itself through other groupings is a cycle that `archsight lint` reports.

Use a grouping when the set is a thing of its own (it has an owner, a description, a page). Resources that only share an
attribute (a team, a tag, a risk domain) are found by a query or a `View`; a place is a `Location`; the wiki menu is a
`PageMenu`.

### Derived References

Text and diagrams already say which resources they are about, so archsight turns that into relations instead of asking you
Expand Down
41 changes: 41 additions & 0 deletions examples/archsight/groupings/payments.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
apiVersion: architecture/v1alpha1
kind: Grouping
metadata:
name: Domain:Payments
annotations:
architecture/description: |
Everything that moves money for the online checkout: the capability, the product, the services and
components that realize it, and the platform they run on. Refunds form a group of their own inside it.
spec:
aggregates:
strategyCapabilities:
- Payment Processing
businessProducts:
- Online Checkout
applicationServices:
- Payment Authorization
technologyServices:
- Payments:Cluster
groupings:
- Domain:Payments:Refunds
composedOf:
applicationComponents:
- Payments:API
- CardVault:API
- Payments:ClusterOperator
---
apiVersion: architecture/v1alpha1
kind: Grouping
metadata:
name: Domain:Payments:Refunds
annotations:
architecture/description: Giving money back to customers, from the service to the worker that does it.
spec:
aggregates:
applicationServices:
- Refunds
composedOf:
applicationComponents:
- Refunds:Worker
technologyArtifacts:
- Repo:refunds-worker
28 changes: 28 additions & 0 deletions lib/archsight/resources.rb
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,31 @@ module Resources
# 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

# Relation keys that do not follow the rule of #relation_key (lowerCamel kind name, made plural): the keys the
# model has used for these kinds from the start
IRREGULAR_RELATION_KEYS = {
"Analysis" => "analyses",
"MotivationGoal" => "goals",
"MotivationOutcome" => "outcomes",
"Page" => "pages",
"PageMenu" => "menus",
"TechnologyEquipment" => "technologyEquipment",
"TechnologySystemSoftware" => "technologySystemSoftware"
}.freeze

# The key under `spec.<verb>` that holds resources of a kind (ApplicationComponent -> applicationComponents),
# for relations that are declared for many kinds at once (see Grouping)
def self.relation_key(kind_name)
name = kind_name.to_s
IRREGULAR_RELATION_KEYS.fetch(name) do
key = name[0].downcase + name[1..]
if key.end_with?("y") && !key.end_with?("ay", "ey", "oy", "uy") then "#{key.chop}ies"
elsif key.end_with?("s", "x", "ch", "sh") then "#{key}es"
else "#{key}s"
end
end
end

# The current name of a kind, whichever of its names is given
def self.canonical(klass_name)
name = klass_name.to_s
Expand Down Expand Up @@ -90,3 +115,6 @@ module Archsight::Annotations; end
Dir[File.join(__dir__, "annotations", "*.rb")].each { |file| require_relative file }
require_relative "resources/base"
Dir[File.join(__dir__, "resources", "*.rb")].each { |file| require_relative file }

# A Grouping holds resources of every kind, so its relations can only be declared once all kinds are known
Archsight::Resources::Grouping.declare_members!
5 changes: 5 additions & 0 deletions lib/archsight/resources/base.rb
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,11 @@ def self.declared_relations
@declared_relations || []
end

# The relations the template of the kind (`archsight template`, the example of its docs page) shows
def self.template_relations
declared_relations
end

# Every relation a resource of this kind can have: the declared ones and the derived ones (`mentions`,
# `depicts`, see Archsight::References). Everything that follows relations (queries, graphs, impact analysis)
# uses this; what lets a user write or choose relations uses declared_relations.
Expand Down
80 changes: 80 additions & 0 deletions lib/archsight/resources/grouping.rb
Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
# frozen_string_literal: true

# Grouping gathers resources of any kind that belong together by some criterion
class Archsight::Resources::Grouping < Archsight::Resources::Base
include_annotations :git, :architecture

description <<~MD
Gathers resources of any kind, other groupings included, that belong together by some criterion.

## ArchiMate Definition

**Layer:** Other (ArchiMate: composite element)
**Aspect:** Composite

The grouping element aggregates or composes concepts that belong together based on some common
characteristic. Unlike a location, the criterion is not a place: a domain, a programme, a product family,
a migration scope, the subject of a review.

## Usage

Use Grouping to represent:

- Domains and sub-domains (Payments, Identity)
- The scope of a programme, a review or an audit
- A product family that spans business, application and technology resources

## Members

A grouping lists its members in `spec`, one key per kind, under one of two verbs:

- `aggregates`: the member belongs to the group but also stands on its own; it can be in several groups
- `composedOf`: the member is a part of this whole and of no other

```yaml
spec:
aggregates:
applicationComponents: [Payment Gateway]
businessProcesses: [Refund Handling]
groupings: [Card Payments]
composedOf:
dataObjects: [Payment]
```

A grouping can contain groupings, so groups nest; a grouping that contains itself (directly or through
others) is reported by `archsight lint`. Members do not name their groups: a member's page lists the groups
it is in.

## Not this kind

- A place is a `Location`
- The menu of the wiki is a `PageMenu`
- Resources that only share an attribute (a team, a tag, a risk domain) need no grouping: a query or a view
finds them
MD

icon "square-dashed"
layer "other"

# The verbs a grouping holds its members with
MEMBER_VERBS = %i[aggregates composedOf].freeze

# The relations shown in the template of the kind; the declared ones cover every kind
TEMPLATE_KINDS = %w[ApplicationComponent BusinessProcess Grouping].freeze

class << self
# Declares MEMBER_VERBS towards every kind, this one included. Called once all kinds are loaded (see
# lib/archsight/resources.rb), since a class body only sees the kinds loaded before it.
def declare_members!
@declared_relations = []
@relations = nil
MEMBER_VERBS.each do |verb|
Archsight::Resources.each { |kind| relation verb, Archsight::Resources.relation_key(kind).to_sym, kind }
end
end

def template_relations
declared_relations.select { |_, _, kind| TEMPLATE_KINDS.include?(kind) }
end
end
end
10 changes: 10 additions & 0 deletions lib/archsight/summary/lens.rb
Original file line number Diff line number Diff line change
Expand Up @@ -40,13 +40,15 @@ class ParseError < StandardError; end
in assesses, influences: Assessed and influenced by
out evidencedBy: Evidence
out ownedBy: Owners
in aggregates, composedOf: Groups
in mentions, depicts: Documented in
LENS
"strategy" => <<~LENS,
out realizes: Realizes
out servedBy: Served by
in hasConcern: Stakeholders
in realizes: Realized by
in aggregates, composedOf: Groups
in mentions, depicts: Documented in
LENS
"implementation" => <<~LENS,
Expand All @@ -59,6 +61,7 @@ class ParseError < StandardError; end
out realizes: Realizes
in realizes: Realized by
out performedBy, ownedBy: People
in aggregates, composedOf: Groups
in mentions, depicts: Documented in
LENS
"business" => <<~LENS,
Expand Down Expand Up @@ -88,6 +91,7 @@ class ParseError < StandardError; end
out evidencedBy: Evidence
in servedBy: Served
in exposes: Exposed by
in aggregates, composedOf: Groups
in mentions, depicts: Documented in
LENS
"technology" => <<~LENS,
Expand All @@ -111,6 +115,12 @@ class ParseError < StandardError; end

# Kinds whose layer lens is too coarse; looked up before the lens of the layer
KIND_DEFAULTS = {
"Grouping" => <<~LENS,
out aggregates: Members
out composedOf: Composed of
in aggregates, composedOf: Part of
in mentions, depicts: Documented in
LENS
"BusinessActor" => <<~LENS,
in performedBy, executedBy: Performs
in ownedBy: Owns
Expand Down
4 changes: 2 additions & 2 deletions lib/archsight/template.rb
Original file line number Diff line number Diff line change
Expand Up @@ -35,10 +35,10 @@ def add_annotations(yaml, klass)
end

def add_relations(yaml, klass)
return if klass.declared_relations.empty?
return if klass.template_relations.empty?

yaml["spec"] = {} if yaml["spec"].nil?
klass.declared_relations.each do |verb, relation_kind, _relation_klass|
klass.template_relations.each do |verb, relation_kind, _relation_klass|
relation_verb = verb.to_s.delete_prefix(":")
yaml["spec"][relation_verb] ||= {}
yaml["spec"][relation_verb][relation_kind.to_s] = []
Expand Down
4 changes: 4 additions & 0 deletions sig/archsight/resources.rbs
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,9 @@ module Archsight
DERIVED_VERBS: Array[Symbol]
DERIVED_KEY: Symbol
DERIVED_RELATIONS: Array[[Symbol, Symbol, String]]
IRREGULAR_RELATION_KEYS: Hash[String, String]

def self.relation_key: (String | Symbol) -> String

def self.register: (untyped) -> void
def self.resource_classes: () -> Hash[String, singleton(Base)]
Expand All @@ -29,6 +32,7 @@ module Archsight
MAX_SUMMARY_ANNOTATIONS: Integer
def self.declared_relations: () -> Array[[Symbol, Symbol, String]]
def self.relations: () -> Array[[Symbol, Symbol, String]]
def self.template_relations: () -> Array[[Symbol, Symbol, String]]
def self.annotation: (String, ?description: String?, ?filter: Symbol?, ?title: String?, ?format: Symbol?, ?enum: Array[String]?, ?sidebar: bool, ?type: Class?, ?summary: bool, ?editor: bool, ?validator: (^(String) -> String?)?, ?unique: bool, ?deprecated: String?) -> void
def self.annotations: () -> Array[Annotations::Annotation]
def self.computed_annotation: (String, ?description: String?, ?filter: Symbol?, ?title: String?, ?format: Symbol?, ?enum: Array[String]?, ?sidebar: bool, ?type: Class?, ?summary: bool) { () -> untyped } -> void
Expand Down
Loading
Loading