Merge pull request #139 from mlabs-haskell/avnik/indirection-layer-for-node

documentation for indirection layer

Author: aciceri

docs/getting-started/providers.md

@@ -0,0 +1,41 @@
+## Cardano Providers Module
+
+### Introduction
+
+The Cardano Providers module defines a common interface for services that depend on a Cardano node.
+Instead of binding directly to a specific systemd unit, services interact with an abstract provider.
+This indirection makes it possible to switch seamlessly between different backends
+(for example, a local `cardano-node` or a remote tunnel such as Demeter)
+without changing service configuration.
+
+The module ensures that shared options and access rules are consistent across all consumers, while hiding implementation details of the underlying node.
+
+### Design Rationale
+
+This design has several advantages:
+
+- **Flexibility** – a consumer does not need to know whether the node is provided locally or remotely.
+- **Transparency** – switching between a local `cardano-node` and a remote tunnel (e.g., from Demeter) requires no changes on the consumer side.
+- **Reusability** – common configuration options are centralized and can be shared across different providers.
+- **Consistency** – consumers operate against a unified contract, regardless of the actual implementation.
+
+### Contract and Visibility
+
+Options under `cardano.provider.*` should be set only in respective provider implementations,
+and only referenced in other services.
+
+If a service provider is enabled, it must set `cardano.provider.$servicename.active = true`.
+Consumers can check `cardano.provider.$servicename.active` for service presence and use provider values without additional checks.
+
+### Service Integration Guidelines
+
+All new services added under `cardano.nix` must integrate exclusively through the provider interface:
+
+- Services must use `cardano.providers.node.socketPath` to locate the node socket.
+
+- Services must respect `cardano.providers.node.accessGroup` for Unix group-based permissions.
+
+- Direct references to a particular `cardano-node` systemd unit or its implementation details are forbidden.
+
+This rule applies not only to Cardano consumers like `cardano-cli` or monitoring tools, but also to middleware services such as Ogmios, Kupo, and others.
+The goal is to guarantee that any consumer can transparently switch between different backends (local node, remote tunnel, etc.) without reconfiguration.

docs/mkdocs.yml

@@ -65,6 +65,7 @@ nav:
       - Deploy: getting-started/deploy.md
       - Load Balancer: getting-started/load-balancer.md
       - Deploy to Cloud: getting-started/cloud.md
+      - Providers: getting-started/providers.md
   - Development:
       - development/develop.md
       - development/contributing.md