Add event sourcing docs to architecture section

Author: ch1bo

docs/docs/dev/architecture/architecture-c4.puml

@@ -5,6 +5,7 @@ title "Hydra Components"
 AddElementTag("external", $bgColor="#23aa12")
 
 Container_Boundary(hydra_node, "Hydra Node") {
+   Component(events, "Events", "", "Event source and sink", $link="https://github.com/cardano-scaling/hydra/blob/master/hydra-node/src/Hydra/Events.hs")
    Component(persistence, "Persistence", "JSON/FS", "Persists state of the head on disk", $link="https://github.com/cardano-scaling/hydra/blob/master/hydra-node/src/Hydra/Persistence.hs")
    Component(head_logic, "Head Logic", "", "Maintains internal Head state and processes events", $link="https://github.com/cardano-scaling/hydra/blob/master/hydra-node/src/Hydra/HeadLogic.hs")
    Component(api_server, "API Server", "", "Handle client commands & queries and serves outputs", $link="https://github.com/cardano-scaling/hydra/blob/master/hydra-node/src/Hydra/API/Server.hs")
@@ -15,6 +16,7 @@ Container_Boundary(hydra_node, "Hydra Node") {
    Component(monitoring, "Monitoring", "", "Exposes Prometheus metrics", $link="https://github.com/cardano-scaling/hydra/blob/master/hydra-node/src/Hydra/Logging/Monitoring.hs")
    Component(ledger, "Cardano Ledger", "", "Maintains Layer 2 State", $tags="external")
 
+   Lay_U(head_logic, events)
    Lay_U(head_logic, persistence)
    Lay_U(head_logic, logging)
    Lay_U(head_logic, monitoring)

docs/docs/dev/event-source.md renamed to docs/docs/dev/architecture/event-sourcing.md

@@ -1,11 +1,9 @@
-## Event sourcing
+# Event sourcing
 
 The `hydra-node` is an event sourced application. This means that the main logic is processing _inputs_ (also called commands) and produces _events_. These events are saved and loaded to persist application state across restarts. Also, most events are transformed to _outputs_ and can be observed on the `hydra-node` API.
 
 On application startup, the [`hydrate`](https://hydra.family/head-protocol/haddock/hydra-node/Hydra-Node.html#v:hydrate) function is called to load all events using a given [`EventSource`](https://hydra.family/head-protocol/haddock/hydra-node/Hydra-Events.html#t:EventSource) and while doing so, re-emits those events to all provided [`EventSink`](https://hydra.family/head-protocol/haddock/hydra-node/Hydra-Events.html#t:EventSink) instances. The resulting [`HydraNode`](https://hydra.family/head-protocol/haddock/hydra-node/Hydra-Node.html#t:HydraNode) will then enter the main loop of `hydra-node` and process inputs into state changes and effects via function [`stepHydraNode`](https://hydra.family/head-protocol/haddock/hydra-node/Hydra-Node.html#v:stepHydraNode). All state changes of a Hydra node are based on [`StateEvent`](https://hydra.family/head-protocol/haddock/hydra-node/Hydra-Events.html#t:StateEvent) values and consequently get emitted to all `eventSinks` of the `HydraNode` handle. Also, the `eventSource` of the same may be used later to to load events on-demand, for example to produce a history of server outputs.
 
-- TODO: explain `StateEvent` data type and `EventSource` / `EventSink` interfaces
-
 ## Default event source and sinks
 
 The default event source and sink used by the `hydra-node` is `FileBased`, which uses an append-only plain JSON file to persist events in a file name `state`. This single file is located in the `hydra-node` persistence directory, which is specified by the `--persistence-dir` command line option. 

docs/docs/dev/architecture/hydra-components.svg

@@ -21,6 +21,10 @@ $ plantuml -Tsvg architecture-c4.puml
 
 :::
 
+### Event sourcing
+
+The `hydra-node` is an event sourced application. This means that the main logic is processing _inputs_ (also called commands) and produces _events_. These events are saved and loaded to persist application state across restarts. Also, most events are transformed to _outputs_ and can be observed on the API. See [Event Sourcing](./architecture/event-sourcing) for details.
+
 ### Network
 
 The _network_ component is responsible for communication between Hydra nodes related to the off-chain part of the Hydra protocol. See [Networking](./architecture/networking) for details.

docs/docs/dev/architecture/index.md

@@ -69,7 +69,7 @@ module.exports = {
       type: "category",
       link: { type: "doc", id: "dev/architecture/index" },
       label: "Architecture",
-      items: ["dev/architecture/networking"],
+      items: ["dev/architecture/event-sourcing", "dev/architecture/networking"],
     },
     {
       type: "doc",