Add documentation on data models

Signed-off-by: Karel van Klink <karel.vanklink@geant.org>

docs/architecture/index.md

@@ -8,7 +8,8 @@ versions all configuration, and it's also responsible for managing mechanisms su
 
 The stack of tools is kept limited:
 
-* Ansible is the tool that deploys configuration and orchestrates changes.
+* Workflow Orchestrator ({term}`WFO`) orchestrates all changes.
+* Ansible is the tool that deploys configuration.
 * If needed, custom Python scripts can support extra functionality.
 
 This approach works well for the deployment of 'base configuration'. For service fulfillment, three more components are
@@ -18,7 +19,10 @@ introduced:
 * A service database.
 * A workflow engine.
 
+All three of these components are deployed as part of {term}`WFO`. More information about {term}`WFO` can be found on
+their website <a href="https://workfloworchestrator.org/" target="_blank">here</a>.
 
+(configuration-decomposition)=
 ## Configuration (de)composition
 
 The configuration of a network element can be decomposed in different functional parts:
@@ -75,48 +79,3 @@ All services offered can be summarised in the following four categories. Some ex
 |---------|-------------|------------------|
 | Layer 2 | VPLS / EVPN | Layer 2 circuits |
 | Layer 3 | L3VPN       | Core links       |
-
-### Decomposition of objects
-
-Every object -- both services and access ports -- is composed of the following building blocks:
-* Administrative metadata
-  * Object ID
-  * Status
-  * Owner
-* Configuration data that depends on the specific service, some examples:
-  * Access port
-    * Access port type
-    * Physical interfaces
-  * IP trunk
-    * IPv4 network
-    * IPv6 network
-    * IS-IS metric
-* Placement metadata
-  * Access node
-  * Service delivery point
-
-
-### Services and ports
-
-While a port shouldn't be configured in case there is no service insisting on it, it could happen that multiple
-services are insisting on the same port. For this reason, we define the following entities:
-
-{term}`SDP`
-: Service Delivery Point: the logical interface where a service is delivered
-
-{term}`GA`
-: Access Port: an access point into the GÉANT network
-
-{term}`GP`
-: Physical Port: the physical boundary for the {term}`GA`
-
-{term}`GAN`
-: Access Node: the node where a service is delivered
-
-These concepts apply to both {term}`CFS`es and {term}`IFS`es.
-
-```{figure} ../static/access_port_diagram.png
-:alt: Diagram that displays the different entities that make up a GÉANT service.
-
-A visualisation of how services insist on ports.
-```

docs/glossary.md

@@ -34,6 +34,9 @@ MPLS
 MTTR
 : Mean Time To Repair
 
+MTU
+: Maximum Transmission Unit
+
 OOB
 : Out-of-band
 

docs/index.md

@@ -3,7 +3,7 @@
 Welcome to the documentation of the GÉANT Automation Platform, or {term}`GAP` for short. \
 The focus of this platform is configuration management and service orchestration for the GÉANT IP/{term}`MPLS` network.
 
-This documentation contains the following sections:
+This documentation has the following sections:
 
 ```{toctree}
 :caption: Background
@@ -12,6 +12,13 @@ overview/index.md
 architecture/index.md
 ```
 
+```{toctree}
+:caption: Modeling
+:maxdepth: 2
+modeling/index.md
+modeling/ports.md
+```
+
 ```{toctree}
 :caption: Processes
 :maxdepth: 2

docs/modeling/index.md

+# Data models
+
+To be able to model network objects, a data model must exist for every configuration item in the network. This allows
+for describing the network, and the services as a composition of abstract objects.
+
+## Decomposition of objects
+
+Every object -- both services and access ports -- is composed of the following building blocks:
+* Administrative metadata
+  * Object ID
+  * Status
+  * Owner
+* Configuration data that depends on the specific service, some examples:
+  * Access port
+    * Access port type
+    * Physical interfaces
+  * IP trunk
+    * IPv4 network
+    * IPv6 network
+    * IS-IS metric
+* Placement metadata
+  * Access node
+  * Service delivery point

docs/modeling/ports.md

+# Services and ports
+
+While a port shouldn't be configured in case there is no service insisting on it, it could happen that more than one
+service is insisting on one port. For this reason, the following entities exist:
+
+{term}`SDP`
+: Service Delivery Point: the logical interface where a service is delivered
+
+{term}`GA`
+: Access Port: an access point into the GÉANT network
+
+{term}`GP`
+: Physical Port: the physical boundary for the {term}`GA`
+
+{term}`GAN`
+: Access Node: the node where a service is delivered
+
+These concepts apply to both {term}`CFS`es and {term}`IFS`es.
+
+```{figure} ../static/access_port_diagram.png
+:alt: Diagram that displays the different entities that make up a GÉANT service.
+
+A visualisation of how services insist on ports.
+```
+
+## Peer-to-peer and multipoint services
+
+There is a distinction between services -- as mentioned in [configuration (de)composition](#configuration-decomposition)
+-- between peer-to-peer and multipoint services. In both cases, {term}`SDP` is the delivery point of a service.
+However, for multipoint services customers are supposed to be dual-homed in at least two different {term}`GAN`s.
+
+To give some examples, the figure below shows a decomposition of a GeantIP service for an NREN.
+
+```{figure} ../static/geant_ip_ports_diagram.png
+:alt: Diagram that displays the different entities that make up a GeantIP service instance.
+
+A visualisation of an instance of a GeantIP service that consists of different configuration objects.
+```

docs/vale/styles/Vocab/geant-jargon/accept.txt

@@ -17,3 +17,6 @@ GAP
 WFO
 BGP
 FXP
+NREN
+MTU
+OOB