# ravendb/ansible-collection-ravendb architecture

> Architecture diagram of the GitHub repository ravendb/ansible-collection-ravendb, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ravendb/ansible-collection-ravendb
- Repository: https://github.com/ravendb/ansible-collection-ravendb

## Overview

This is an Ansible collection for provisioning RavenDB servers and managing RavenDB clusters. The main workflow is an Ansible operator invoking a module, which validates inputs, creates a client context where applicable, and reconciles desired state against RavenDB; database reconciliation also uses service operations and optional encryption. The collection additionally provides node installation roles and modules for connection strings and health checks. Internal links are limited to relationships visible in excerpts; the README documents the collection’s broader capabilities.

Main entry points: [`plugins/modules/database.py`](https://github.com/ravendb/ansible-collection-ravendb/blob/main/plugins/modules/database.py) (Database Module), [`plugins/module_utils/reconcilers/database_reconciler.py`](https://github.com/ravendb/ansible-collection-ravendb/blob/main/plugins/module_utils/reconcilers/database_reconciler.py) (Database Reconciler), [`plugins/modules/index.py`](https://github.com/ravendb/ansible-collection-ravendb/blob/main/plugins/modules/index.py) (Index Module), [`plugins/module_utils/core/client.py`](https://github.com/ravendb/ansible-collection-ravendb/blob/main/plugins/module_utils/core/client.py) (Document Store Factory)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_provision["Server Provisioning"]
  node_node_role["Node Role"]
  node_python_role["Client Prerequisites"]
end

subgraph group_modules["Ansible Modules"]
  node_database_module["Database Module<br/>[database.py]"]
  node_index_module["Index Module<br/>[index.py]"]
  node_node_module["Node Module<br/>[node.py]"]
  node_connection_module["Connection String Module"]
  node_health_module["Healthcheck Module<br/>[healthcheck.py]"]
end

subgraph group_runtime["Module Runtime"]
  node_validation["Input Validation<br/>[validation.py]"]
  node_client_factory["Document Store Factory<br/>[client.py]"]
  node_dependency_check["Client Dependency Check<br/>[deps.py]"]
  node_database_spec["Database Specification<br/>[database.py]"]
end

subgraph group_domain["Domain Operations"]
  node_database_reconciler["Database Reconciler"]
  node_database_service["Database Operations"]
  node_settings_service["Database Settings"]
  node_encryption_service["Encryption Operations"]
  node_cluster_service["Cluster Operations<br/>[cluster_service.py]"]
  node_index_reconciler["Index Reconciler"]
  node_index_service["Index Operations<br/>[index_service.py]"]
  node_connection_service["Connection String Operations"]
  node_health_service["Healthcheck Operations"]
  node_node_service["Node Operations<br/>[node_service.py]"]
end

node_operator(("Ansible Operator"))
node_ravendb[("RavenDB Server")]

node_operator -->|"provisions with"| node_node_role
node_operator -->|"installs prerequisites"| node_python_role
node_node_role -->|"installs and configures"| node_ravendb
node_operator -->|"invokes"| node_database_module
node_operator -->|"invokes"| node_index_module
node_operator -->|"invokes"| node_node_module
node_operator -.->|"invokes"| node_connection_module
node_operator -.->|"invokes"| node_health_module
node_database_module -->|"validates inputs"| node_validation
node_database_module -.->|"creates context"| node_client_factory
node_database_module -->|"delegates reconciliation"| node_database_reconciler
node_database_module -.->|"builds specification"| node_database_spec
node_database_module -->|"validates encryption"| node_encryption_service
node_client_factory -->|"requires client"| node_dependency_check
node_database_reconciler -->|"reads and mutates databases"| node_database_service
node_database_reconciler -->|"applies settings"| node_settings_service
node_database_reconciler -->|"handles encryption"| node_encryption_service
node_database_reconciler -->|"checks topology"| node_cluster_service
node_index_module -->|"delegates reconciliation"| node_index_reconciler
node_index_module -->|"creates context"| node_client_factory
node_index_module -.->|"reads index definition"| node_index_service
node_index_reconciler -.->|"uses operations"| node_index_service
node_connection_module -.->|"manages connection strings"| node_connection_service
node_health_module -.->|"checks cluster health"| node_health_service
node_node_module -.->|"manages cluster nodes"| node_node_service

click node_node_role "https://github.com/ravendb/ansible-collection-ravendb/tree/main/roles/ravendb_node"
click node_python_role "https://github.com/ravendb/ansible-collection-ravendb/tree/main/roles/ravendb_python_client_prerequisites"
click node_database_module "https://github.com/ravendb/ansible-collection-ravendb/blob/main/plugins/modules/database.py"
click node_index_module "https://github.com/ravendb/ansible-collection-ravendb/blob/main/plugins/modules/index.py"
click node_node_module "https://github.com/ravendb/ansible-collection-ravendb/blob/main/plugins/modules/node.py"
click node_connection_module "https://github.com/ravendb/ansible-collection-ravendb/blob/main/plugins/modules/connection_string.py"
click node_health_module "https://github.com/ravendb/ansible-collection-ravendb/blob/main/plugins/modules/healthcheck.py"
click node_validation "https://github.com/ravendb/ansible-collection-ravendb/blob/main/plugins/module_utils/core/validation.py"
click node_client_factory "https://github.com/ravendb/ansible-collection-ravendb/blob/main/plugins/module_utils/core/client.py"
click node_dependency_check "https://github.com/ravendb/ansible-collection-ravendb/blob/main/plugins/module_utils/core/deps.py"
click node_database_spec "https://github.com/ravendb/ansible-collection-ravendb/blob/main/plugins/module_utils/dto/database.py"
click node_database_reconciler "https://github.com/ravendb/ansible-collection-ravendb/blob/main/plugins/module_utils/reconcilers/database_reconciler.py"
click node_database_service "https://github.com/ravendb/ansible-collection-ravendb/blob/main/plugins/module_utils/services/database_service.py"
click node_settings_service "https://github.com/ravendb/ansible-collection-ravendb/blob/main/plugins/module_utils/services/db_settings_service.py"
click node_encryption_service "https://github.com/ravendb/ansible-collection-ravendb/blob/main/plugins/module_utils/services/encryption_service.py"
click node_cluster_service "https://github.com/ravendb/ansible-collection-ravendb/blob/main/plugins/module_utils/services/cluster_service.py"
click node_index_reconciler "https://github.com/ravendb/ansible-collection-ravendb/blob/main/plugins/module_utils/reconcilers/index_reconciler.py"
click node_index_service "https://github.com/ravendb/ansible-collection-ravendb/blob/main/plugins/module_utils/services/index_service.py"
click node_connection_service "https://github.com/ravendb/ansible-collection-ravendb/blob/main/plugins/module_utils/services/connection_string_service.py"
click node_health_service "https://github.com/ravendb/ansible-collection-ravendb/blob/main/plugins/module_utils/services/healthcheck_service.py"
click node_node_service "https://github.com/ravendb/ansible-collection-ravendb/blob/main/plugins/module_utils/services/node_service.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_role,node_python_role toneBlue
class node_database_module,node_index_module,node_node_module,node_connection_module,node_health_module,node_ravendb toneAmber
class node_validation,node_client_factory,node_dependency_check,node_database_spec toneMint
class node_database_reconciler,node_database_service,node_settings_service,node_encryption_service,node_cluster_service,node_index_reconciler,node_index_service,node_connection_service,node_health_service,node_node_service toneRose
class node_operator toneIndigo
```

## Components

### Server Provisioning

- [Node Role](https://github.com/ravendb/ansible-collection-ravendb/tree/main/roles/ravendb_node): `roles/ravendb_node`
- [Client Prerequisites](https://github.com/ravendb/ansible-collection-ravendb/tree/main/roles/ravendb_python_client_prerequisites): `roles/ravendb_python_client_prerequisites`

### Ansible Modules

- [Database Module](https://github.com/ravendb/ansible-collection-ravendb/blob/main/plugins/modules/database.py): `plugins/modules/database.py`
- [Index Module](https://github.com/ravendb/ansible-collection-ravendb/blob/main/plugins/modules/index.py): `plugins/modules/index.py`
- [Node Module](https://github.com/ravendb/ansible-collection-ravendb/blob/main/plugins/modules/node.py): `plugins/modules/node.py`
- [Connection String Module](https://github.com/ravendb/ansible-collection-ravendb/blob/main/plugins/modules/connection_string.py): `plugins/modules/connection_string.py`
- [Healthcheck Module](https://github.com/ravendb/ansible-collection-ravendb/blob/main/plugins/modules/healthcheck.py): `plugins/modules/healthcheck.py`

### Module Runtime

- [Input Validation](https://github.com/ravendb/ansible-collection-ravendb/blob/main/plugins/module_utils/core/validation.py): `plugins/module_utils/core/validation.py`
- [Document Store Factory](https://github.com/ravendb/ansible-collection-ravendb/blob/main/plugins/module_utils/core/client.py): `plugins/module_utils/core/client.py`
- [Client Dependency Check](https://github.com/ravendb/ansible-collection-ravendb/blob/main/plugins/module_utils/core/deps.py): `plugins/module_utils/core/deps.py`
- [Database Specification](https://github.com/ravendb/ansible-collection-ravendb/blob/main/plugins/module_utils/dto/database.py): `plugins/module_utils/dto/database.py`

### Domain Operations

- [Database Reconciler](https://github.com/ravendb/ansible-collection-ravendb/blob/main/plugins/module_utils/reconcilers/database_reconciler.py): `plugins/module_utils/reconcilers/database_reconciler.py`
- [Database Operations](https://github.com/ravendb/ansible-collection-ravendb/blob/main/plugins/module_utils/services/database_service.py): `plugins/module_utils/services/database_service.py`
- [Database Settings](https://github.com/ravendb/ansible-collection-ravendb/blob/main/plugins/module_utils/services/db_settings_service.py): `plugins/module_utils/services/db_settings_service.py`
- [Encryption Operations](https://github.com/ravendb/ansible-collection-ravendb/blob/main/plugins/module_utils/services/encryption_service.py): `plugins/module_utils/services/encryption_service.py`
- [Cluster Operations](https://github.com/ravendb/ansible-collection-ravendb/blob/main/plugins/module_utils/services/cluster_service.py): `plugins/module_utils/services/cluster_service.py`
- [Index Reconciler](https://github.com/ravendb/ansible-collection-ravendb/blob/main/plugins/module_utils/reconcilers/index_reconciler.py): `plugins/module_utils/reconcilers/index_reconciler.py`
- [Index Operations](https://github.com/ravendb/ansible-collection-ravendb/blob/main/plugins/module_utils/services/index_service.py): `plugins/module_utils/services/index_service.py`
- [Connection String Operations](https://github.com/ravendb/ansible-collection-ravendb/blob/main/plugins/module_utils/services/connection_string_service.py): `plugins/module_utils/services/connection_string_service.py`
- [Healthcheck Operations](https://github.com/ravendb/ansible-collection-ravendb/blob/main/plugins/module_utils/services/healthcheck_service.py): `plugins/module_utils/services/healthcheck_service.py`
- [Node Operations](https://github.com/ravendb/ansible-collection-ravendb/blob/main/plugins/module_utils/services/node_service.py): `plugins/module_utils/services/node_service.py`

### Other components

- **Ansible Operator**
- **RavenDB Server**

## Connections

- Ansible Operator → Node Role: provisions with (evidence: `README.md`)
- Ansible Operator → Client Prerequisites: installs prerequisites (evidence: `README.md`)
- Node Role → RavenDB Server: installs and configures (evidence: `README.md`)
- Ansible Operator → Database Module: invokes (evidence: `README.md`)
- Ansible Operator → Index Module: invokes (evidence: `README.md`)
- Ansible Operator → Node Module: invokes (evidence: `README.md`)
- Ansible Operator → Connection String Module: invokes
- Ansible Operator → Healthcheck Module: invokes
- Database Module → Input Validation: validates inputs (evidence: `plugins/modules/database.py`)
- Database Module → Document Store Factory: creates context
- Database Module → Database Reconciler: delegates reconciliation (evidence: `plugins/modules/database.py`)
- Database Module → Database Specification: builds specification
- Database Module → Encryption Operations: validates encryption (evidence: `plugins/modules/database.py`)
- Document Store Factory → Client Dependency Check: requires client (evidence: `plugins/module_utils/core/client.py`)
- Database Reconciler → Database Operations: reads and mutates databases (evidence: `plugins/module_utils/reconcilers/database_reconciler.py`)
- Database Reconciler → Database Settings: applies settings (evidence: `plugins/module_utils/reconcilers/database_reconciler.py`)
- Database Reconciler → Encryption Operations: handles encryption (evidence: `plugins/module_utils/reconcilers/database_reconciler.py`)
- Database Reconciler → Cluster Operations: checks topology (evidence: `plugins/module_utils/reconcilers/database_reconciler.py`)
- Index Module → Index Reconciler: delegates reconciliation (evidence: `plugins/modules/index.py`)
- Index Module → Document Store Factory: creates context (evidence: `plugins/modules/index.py`)
- Index Module → Index Operations: reads index definition
- Index Reconciler → Index Operations: uses operations
- Connection String Module → Connection String Operations: manages connection strings
- Healthcheck Module → Healthcheck Operations: checks cluster health
- Node Module → Node Operations: manages cluster nodes