# ezequielribeiro/distributed-server-manager architecture

> Architecture diagram of the GitHub repository ezequielribeiro/distributed-server-manager, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ezequielribeiro/distributed-server-manager
- Repository: https://github.com/ezequielribeiro/distributed-server-manager

## Overview

Capivara DSM is a distributed, multi-game server manager with a Controller, Linux/Windows Agents, and a hybrid mode. Its main customer workflow is contract-authorized instance creation: the Controller selects a suitable Agent, ensures shared game data is available, then asks the Agent to materialize and operate the instance. Other major capabilities include catalog and content management, backups, maintenance, observability and alerts, and storage-pool migration. The README documents the broad architecture; sampled source supports several Agent, persistence, and alerting details, but not every Controller-to-Agent dispatch.

Main entry points: [`dashboard/agent_instance_provisioning_api.py`](https://github.com/ezequielribeiro/distributed-server-manager/blob/main/dashboard/agent_instance_provisioning_api.py) (Provisioning), [`agents/linux/runtime/agent.py`](https://github.com/ezequielribeiro/distributed-server-manager/blob/main/agents/linux/runtime/agent.py) (Linux Agent), [`agents/linux/runtime/instance_runtime.py`](https://github.com/ezequielribeiro/distributed-server-manager/blob/main/agents/linux/runtime/instance_runtime.py) (Instance Runtime), [`dashboard/instance_creation_http.py`](https://github.com/ezequielribeiro/distributed-server-manager/blob/main/dashboard/instance_creation_http.py) (Instance Creation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Controller and Dashboard"]
  node_customer_api["Customer APIs"]
  node_instance_creation["Instance Creation"]
  node_placement["Placement"]
  node_agent_fleet["Agent Fleet<br/>[agent_lifecycle.py]"]
end

subgraph group_catalog["Catalog and Provisioning"]
  node_catalog_runtime["Catalog Runtime<br/>[catalog_index.py]"]
  node_game_data["Game Data"]
  node_provisioning["Provisioning"]
end

subgraph group_agent["Agent Runtime"]
  node_linux_agent["Linux Agent<br/>[agent.py]"]
  node_windows_agent["Windows Agent<br/>[agent.py]"]
  node_instance_runtime["Instance Runtime"]
  node_materializer["Privileged Materializer"]
  node_runtime_operations["Operation Journal"]
end

subgraph group_operations["Operations and Content"]
  node_content["Content Management<br/>[content_api.py]"]
  node_backup["Backup<br/>[backup_client.py]"]
  node_maintenance["Maintenance"]
  node_storage_migration["Storage Migration"]
  node_storage_pools["Storage Pools<br/>[storage_pools.py]"]
end

subgraph group_persistence["Persistence and Events"]
  node_database[("Database<br/>[backend.py]")]
  node_configuration["Configuration Repository"]
  node_events["Universal Events"]
  node_alerts["Alert Evaluator<br/>[alert_engine.py]"]
  node_alert_repository["Alert Repository"]
end

node_customer(("Customer"))
node_admin(("Administrator"))

node_customer -->|"requests service"| node_customer_api
node_customer_api -.->|"starts creation"| node_instance_creation
node_admin -->|"manages catalog"| node_catalog_runtime
node_instance_creation -->|"requests placement"| node_placement
node_placement -->|"selects Agent"| node_agent_fleet
node_instance_creation -->|"coordinates provisioning"| node_provisioning
node_provisioning -->|"ensures game data"| node_game_data
node_provisioning -->|"dispatches provisioning"| node_linux_agent
node_provisioning -->|"dispatches provisioning"| node_windows_agent
node_catalog_runtime -->|"defines runtime needs"| node_game_data
node_linux_agent -->|"observes instances"| node_instance_runtime
node_linux_agent -->|"invokes materializer"| node_materializer
node_materializer -->|"registers instance"| node_instance_runtime
node_instance_runtime -.->|"journals operations"| node_runtime_operations
node_admin -->|"manages content"| node_content
node_admin -->|"operates backups"| node_backup
node_maintenance -.->|"coordinates maintenance"| node_linux_agent
node_admin -->|"configures pools"| node_storage_pools
node_storage_migration -->|"resolves pools"| node_storage_pools
node_storage_migration -->|"registers after rollback"| node_instance_runtime
node_configuration -->|"persists settings"| node_database
node_events -.->|"stores events"| node_database
node_alerts -->|"evaluates and reconciles"| node_alert_repository
node_alert_repository -->|"persists alerts"| node_database

click node_customer_api "https://github.com/ezequielribeiro/distributed-server-manager/blob/main/dashboard/customer_instance_creation.py"
click node_instance_creation "https://github.com/ezequielribeiro/distributed-server-manager/blob/main/dashboard/instance_creation_http.py"
click node_placement "https://github.com/ezequielribeiro/distributed-server-manager/blob/main/core/placement/placement_policy.py"
click node_agent_fleet "https://github.com/ezequielribeiro/distributed-server-manager/blob/main/core/agent_lifecycle.py"
click node_catalog_runtime "https://github.com/ezequielribeiro/distributed-server-manager/blob/main/core/catalog_index.py"
click node_game_data "https://github.com/ezequielribeiro/distributed-server-manager/blob/main/core/content_platform.py"
click node_provisioning "https://github.com/ezequielribeiro/distributed-server-manager/blob/main/dashboard/agent_instance_provisioning_api.py"
click node_linux_agent "https://github.com/ezequielribeiro/distributed-server-manager/blob/main/agents/linux/runtime/agent.py"
click node_windows_agent "https://github.com/ezequielribeiro/distributed-server-manager/blob/main/agents/windows/runtime/agent.py"
click node_instance_runtime "https://github.com/ezequielribeiro/distributed-server-manager/blob/main/agents/linux/runtime/instance_runtime.py"
click node_materializer "https://github.com/ezequielribeiro/distributed-server-manager/blob/main/agents/linux/runtime/privileged_materialization.py"
click node_runtime_operations "https://github.com/ezequielribeiro/distributed-server-manager/blob/main/agents/linux/runtime/runtime_operations.py"
click node_content "https://github.com/ezequielribeiro/distributed-server-manager/blob/main/dashboard/content_api.py"
click node_backup "https://github.com/ezequielribeiro/distributed-server-manager/blob/main/agents/linux/runtime/backup_client.py"
click node_maintenance "https://github.com/ezequielribeiro/distributed-server-manager/blob/main/dashboard/workers/maintenance_worker.py"
click node_storage_migration "https://github.com/ezequielribeiro/distributed-server-manager/blob/main/agents/linux/runtime/storage_pool_migration_executor.py"
click node_storage_pools "https://github.com/ezequielribeiro/distributed-server-manager/blob/main/agents/linux/runtime/storage_pools.py"
click node_database "https://github.com/ezequielribeiro/distributed-server-manager/blob/main/database/backend.py"
click node_configuration "https://github.com/ezequielribeiro/distributed-server-manager/blob/main/database/configuration_repository.py"
click node_events "https://github.com/ezequielribeiro/distributed-server-manager/blob/main/database/universal_event_repository.py"
click node_alerts "https://github.com/ezequielribeiro/distributed-server-manager/blob/main/monitor/alert_engine.py"
click node_alert_repository "https://github.com/ezequielribeiro/distributed-server-manager/blob/main/database/alert_repository.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_customer_api,node_instance_creation,node_placement,node_agent_fleet toneBlue
class node_catalog_runtime,node_game_data,node_provisioning toneAmber
class node_linux_agent,node_windows_agent,node_instance_runtime,node_materializer,node_runtime_operations toneMint
class node_content,node_backup,node_maintenance,node_storage_migration,node_storage_pools toneRose
class node_database,node_configuration,node_events,node_alerts,node_alert_repository,node_customer,node_admin toneIndigo
```

## Components

### Controller and Dashboard

- [Customer APIs](https://github.com/ezequielribeiro/distributed-server-manager/blob/main/dashboard/customer_instance_creation.py): `dashboard/customer_instance_creation.py`
- [Instance Creation](https://github.com/ezequielribeiro/distributed-server-manager/blob/main/dashboard/instance_creation_http.py): `dashboard/instance_creation_http.py`
- [Placement](https://github.com/ezequielribeiro/distributed-server-manager/blob/main/core/placement/placement_policy.py): `core/placement/placement_policy.py`
- [Agent Fleet](https://github.com/ezequielribeiro/distributed-server-manager/blob/main/core/agent_lifecycle.py): `core/agent_lifecycle.py`

### Catalog and Provisioning

- [Catalog Runtime](https://github.com/ezequielribeiro/distributed-server-manager/blob/main/core/catalog_index.py): `core/catalog_index.py`
- [Game Data](https://github.com/ezequielribeiro/distributed-server-manager/blob/main/core/content_platform.py): `core/content_platform.py`
- [Provisioning](https://github.com/ezequielribeiro/distributed-server-manager/blob/main/dashboard/agent_instance_provisioning_api.py): `dashboard/agent_instance_provisioning_api.py`

### Agent Runtime

- [Linux Agent](https://github.com/ezequielribeiro/distributed-server-manager/blob/main/agents/linux/runtime/agent.py): `agents/linux/runtime/agent.py`
- [Windows Agent](https://github.com/ezequielribeiro/distributed-server-manager/blob/main/agents/windows/runtime/agent.py): `agents/windows/runtime/agent.py`
- [Instance Runtime](https://github.com/ezequielribeiro/distributed-server-manager/blob/main/agents/linux/runtime/instance_runtime.py): `agents/linux/runtime/instance_runtime.py`
- [Privileged Materializer](https://github.com/ezequielribeiro/distributed-server-manager/blob/main/agents/linux/runtime/privileged_materialization.py): `agents/linux/runtime/privileged_materialization.py`
- [Operation Journal](https://github.com/ezequielribeiro/distributed-server-manager/blob/main/agents/linux/runtime/runtime_operations.py): `agents/linux/runtime/runtime_operations.py`

### Operations and Content

- [Content Management](https://github.com/ezequielribeiro/distributed-server-manager/blob/main/dashboard/content_api.py): `dashboard/content_api.py`
- [Backup](https://github.com/ezequielribeiro/distributed-server-manager/blob/main/agents/linux/runtime/backup_client.py): `agents/linux/runtime/backup_client.py`
- [Maintenance](https://github.com/ezequielribeiro/distributed-server-manager/blob/main/dashboard/workers/maintenance_worker.py): `dashboard/workers/maintenance_worker.py`
- [Storage Migration](https://github.com/ezequielribeiro/distributed-server-manager/blob/main/agents/linux/runtime/storage_pool_migration_executor.py): `agents/linux/runtime/storage_pool_migration_executor.py`
- [Storage Pools](https://github.com/ezequielribeiro/distributed-server-manager/blob/main/agents/linux/runtime/storage_pools.py): `agents/linux/runtime/storage_pools.py`

### Persistence and Events

- [Database](https://github.com/ezequielribeiro/distributed-server-manager/blob/main/database/backend.py): `database/backend.py`
- [Configuration Repository](https://github.com/ezequielribeiro/distributed-server-manager/blob/main/database/configuration_repository.py): `database/configuration_repository.py`
- [Universal Events](https://github.com/ezequielribeiro/distributed-server-manager/blob/main/database/universal_event_repository.py): `database/universal_event_repository.py`
- [Alert Evaluator](https://github.com/ezequielribeiro/distributed-server-manager/blob/main/monitor/alert_engine.py): `monitor/alert_engine.py`
- [Alert Repository](https://github.com/ezequielribeiro/distributed-server-manager/blob/main/database/alert_repository.py): `database/alert_repository.py`

### Other components

- **Customer**
- **Administrator**

## Connections

- Customer → Customer APIs: requests service (evidence: `README.md`)
- Customer APIs → Instance Creation: starts creation
- Administrator → Catalog Runtime: manages catalog (evidence: `README.md`)
- Instance Creation → Placement: requests placement (evidence: `README.md`)
- Placement → Agent Fleet: selects Agent (evidence: `README.md`)
- Instance Creation → Provisioning: coordinates provisioning (evidence: `README.md`)
- Provisioning → Game Data: ensures game data (evidence: `README.md`)
- Provisioning → Linux Agent: dispatches provisioning (evidence: `README.md`)
- Provisioning → Windows Agent: dispatches provisioning (evidence: `README.md`)
- Catalog Runtime → Game Data: defines runtime needs (evidence: `README.md`)
- Linux Agent → Instance Runtime: observes instances (evidence: `agents/linux/runtime/instance_runtime.py`)
- Linux Agent → Privileged Materializer: invokes materializer (evidence: `agents/linux/runtime/privileged_materialization.py`)
- Privileged Materializer → Instance Runtime: registers instance (evidence: `agents/linux/runtime/privileged_materialization.py`)
- Instance Runtime → Operation Journal: journals operations (evidence: `agents/linux/runtime/instance_runtime.py`)
- Administrator → Content Management: manages content (evidence: `README.md`)
- Administrator → Backup: operates backups (evidence: `README.md`)
- Maintenance → Linux Agent: coordinates maintenance
- Administrator → Storage Pools: configures pools (evidence: `README.md`)
- Storage Migration → Storage Pools: resolves pools (evidence: `agents/linux/runtime/storage_pool_migration_executor.py`)
- Storage Migration → Instance Runtime: registers after rollback (evidence: `agents/linux/runtime/storage_pool_migration_executor.py`)
- Configuration Repository → Database: persists settings (evidence: `database/configuration_repository.py`)
- Universal Events → Database: stores events
- Alert Evaluator → Alert Repository: evaluates and reconciles (evidence: `monitor/alert_engine.py`)
- Alert Repository → Database: persists alerts (evidence: `database/alert_repository.py`)
