Merge branch '71-architecture-document' into 'develop'

Resolve "Architecture Document"

See merge request cocsn/gosdn!99

ARCHITECTURE.md

+# goSDN Architecture
+
+This document describes the the high-level architecture of the goSDN project. All contributors should familiarize themselves with it. To avoid too much divergence from the changing code this document does focus on high-level concepts instead of implementation details.
+
+## Bird's Eye View
+
+[<img src="documentation/architecture.png"  style="height:50%; width:50%" > ](documentation/architecture.png)
+
+On the highest level goSDn provides a gRPC northbound-interface and two types of southbound-interfaces: RESTCONF and gRPC-based. The northbound interface allows the interaction with a running goSDN daemon and may allow the stacking of multiple controllers in the future. The southbound interface (SBI) capabilities are split in `nucleus` models and plugins. The supported `nucleus` models are OpenConfig yang [openconfig-yang](https://github.com/openconfig/yang)  and TAPI. Third party models and more SBI-transports can be attached using the go plugin architecture.
+
+The internal data representation uses [ygot](https://github.com/openconfig/ygot) generated go-structs. 
+It is important to note that these go-structs are generated from yang models and thus are not generic data structures. This means that the `nucleus` code is organized in silos, i.e., one particular southbound-interface is visible in the `nucleus`, as the internal data representation depend on the used yang modes in the southbound-interface.
+
+## Code Map
+
+This section briefly describes important directories and data structures. It also introduces important API calls to relevant libraries.
+
+
+It also mentions **architecture invariants** and **API boundaries**
+### `api`
+
+API specification for gRPC and protobuf definitions.
+
+**Architecture invariant:** To import gRPC related protobuf definitions use `pb` as an import prefix. For gNMI related protobuf definitions use `gpb`
+
+### `forks`
+
+Forks of `google/gnxi/gnmi` and `arista/goarista/gnmi` for gNMI server and client respectively. Subject of change once we converge to own clients and servers.
+
+### `nucleus/principalNetworkDomain`
+
+`nucleus` is the core package of goSDN. The main data structure is the `principalNetworkDomain` (PND). It reflects one administrative entity, i.e., as set of connected network devices,  and is the source of truth for network state and configuration. A PND is SBI agnostic and supports multiple SBI implementations simultaneously. 
+
+**API boundary:** The PND' is the only way to interact with an `orchestratedNetworkingDevice`
+
+### `nucleus/device`
+
+This is the representation of an `orchestratedNetworkingDevice` (OND). An `orchestratedNetworkingDevice` is the network device that is directly managed by goSDN. It holds a reference to the device's `transport` and `southboundInterface` implementation. It contains a fakeroot device based on its attached SBI.
+
+**Architecture invariant:** The device is does not provide any functionality to upper API layers.
+
+### `nucleus/southbound`
+
+Implementation of SBI specifics. Provides SBI models to other callers and SBI specific function deviations.
+
+**Architecture invariant:** Only SBIs defined by a YANG model will be supported by goSDN.
+
+### `nucleus/transport` `nucleus/gnmi_transport` `nucleus/restconf_transport`
+
+Transport between goSDN and ONDs. Current core implementations are gNMI and RESTCONF. Additionally to implementing the transports the packages also provide a mapping from general purpose goSDN API calls to diverging SBI API calls.
+
+For example `gNMI::Subscribe` and `RESTCONF::Push` are mapped to `gosdn::Subscribe`.
+
+The `gnmi_transport` implementation uses `ytypes.SetNode` to write to a device struct.