# olvid-io/olvid-bot-python-client architecture

> Architecture diagram of the GitHub repository olvid-io/olvid-bot-python-client, 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/olvid-io/olvid-bot-python-client
- Repository: https://github.com/olvid-io/olvid-bot-python-client

## Overview

Olvid Bot Python Client exposes an async gRPC API and a built-in CLI for managing a daemon. The main workflow is CLI input routed to domain command handlers, through a selected client and gRPC stubs, to the daemon; results are returned for display or scripting. The client also supports notification streams and listener callbacks, while the repository supplies typed data models, admin operations, and chatbot/monitoring helpers. Some domain modules are unsampled, so their internal calls are not expanded.

Main entry points: [`olvid/core/OlvidClient.py`](https://github.com/olvid-io/olvid-bot-python-client/blob/main/olvid/core/OlvidClient.py) (Olvid client), [`olvid/core/StubHolder.py`](https://github.com/olvid-io/olvid-bot-python-client/blob/main/olvid/core/StubHolder.py) (Stub holder), [`olvid/core/OlvidAdminClient.py`](https://github.com/olvid-io/olvid-bot-python-client/blob/main/olvid/core/OlvidAdminClient.py) (Admin client), [`olvid/cli/handler`](https://github.com/olvid-io/olvid-bot-python-client/tree/main/olvid/cli/handler) (Domain handlers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI"]
  node_cli_entry["CLI entry<br/>[__main__.py]"]
  node_cli_tree["Command tree"]
  node_domain_handlers["Domain handlers"]
  node_cli_helpers["CLI helpers<br/>[cli_tools.py]"]
  node_client_selector["Client selector<br/>[ClientSingleton.py]"]
end

subgraph group_client["Client and transport"]
  node_grpc_client["Olvid client<br/>[OlvidClient.py]"]
  node_admin_client["Admin client"]
  node_tls_config["gRPC TLS"]
  node_stub_holder["Stub holder<br/>[StubHolder.py]"]
end

subgraph group_contracts["API contracts"]
  node_grpc_contracts["gRPC stubs"]
  node_command_contracts["Command contracts<br/>[commands.py]"]
  node_admin_contracts["Admin contracts<br/>[admin.py]"]
  node_notification_contracts["Notification contracts<br/>[notifications.py]"]
  node_data_models["Data models<br/>[datatypes.py]"]
end

subgraph group_events["Events and tools"]
  node_listener_api["Listener API"]
  node_listener_base["Generic listener"]
  node_listener_holder["Listener holder"]
  node_chatbot["Chatbot helper<br/>[ChatBot.py]"]
  node_monitoring["Monitoring helper<br/>[MonitoringBot.py]"]
  node_delayed_tasks["Delayed tasks"]
end

node_operator(("Operator"))
node_daemon["Olvid daemon"]

node_operator -->|"runs"| node_cli_entry
node_cli_entry -->|"dispatches to"| node_cli_tree
node_cli_tree -->|"registers"| node_domain_handlers
node_domain_handlers -.->|"selects client"| node_client_selector
node_domain_handlers -.->|"formats results"| node_cli_helpers
node_client_selector -->|"creates default"| node_admin_client
node_client_selector -->|"creates impersonated"| node_grpc_client
node_grpc_client -->|"uses stubs"| node_stub_holder
node_admin_client -->|"uses stubs"| node_stub_holder
node_grpc_client -->|"uses types"| node_data_models
node_admin_client -->|"uses types"| node_data_models
node_admin_client -->|"configures TLS"| node_tls_config
node_stub_holder -->|"loads contracts"| node_command_contracts
node_stub_holder -->|"loads contracts"| node_admin_contracts
node_stub_holder -->|"loads contracts"| node_notification_contracts
node_grpc_contracts -->|"calls gRPC"| node_daemon
node_grpc_client -->|"accesses RPCs"| node_daemon
node_grpc_client -->|"manages listeners"| node_listener_holder
node_listener_api -->|"extends"| node_listener_base
node_listener_holder -->|"creates iterators"| node_listener_base
node_listener_holder -->|"dispatches callbacks"| node_grpc_client
node_chatbot -->|"subclasses"| node_grpc_client
node_chatbot -->|"uses listeners"| node_listener_api
node_monitoring -->|"uses client"| node_grpc_client
node_delayed_tasks -.->|"schedules tasks"| node_daemon

click node_cli_entry "https://github.com/olvid-io/olvid-bot-python-client/blob/main/olvid/__main__.py"
click node_cli_tree "https://github.com/olvid-io/olvid-bot-python-client/blob/main/olvid/cli/interactive_tree.py"
click node_domain_handlers "https://github.com/olvid-io/olvid-bot-python-client/tree/main/olvid/cli/handler"
click node_cli_helpers "https://github.com/olvid-io/olvid-bot-python-client/blob/main/olvid/cli/tools/cli_tools.py"
click node_client_selector "https://github.com/olvid-io/olvid-bot-python-client/blob/main/olvid/cli/tools/ClientSingleton.py"
click node_grpc_client "https://github.com/olvid-io/olvid-bot-python-client/blob/main/olvid/core/OlvidClient.py"
click node_admin_client "https://github.com/olvid-io/olvid-bot-python-client/blob/main/olvid/core/OlvidAdminClient.py"
click node_tls_config "https://github.com/olvid-io/olvid-bot-python-client/blob/main/olvid/core/GrpcTlsConfiguration.py"
click node_stub_holder "https://github.com/olvid-io/olvid-bot-python-client/blob/main/olvid/core/StubHolder.py"
click node_grpc_contracts "https://github.com/olvid-io/olvid-bot-python-client/tree/main/olvid/protobuf"
click node_command_contracts "https://github.com/olvid-io/olvid-bot-python-client/blob/main/olvid/internal/commands/commands.py"
click node_admin_contracts "https://github.com/olvid-io/olvid-bot-python-client/blob/main/olvid/internal/admin/admin.py"
click node_notification_contracts "https://github.com/olvid-io/olvid-bot-python-client/blob/main/olvid/internal/notifications/notifications.py"
click node_data_models "https://github.com/olvid-io/olvid-bot-python-client/blob/main/olvid/datatypes/datatypes.py"
click node_listener_api "https://github.com/olvid-io/olvid-bot-python-client/blob/main/olvid/listeners/ListenersImplementation.py"
click node_listener_base "https://github.com/olvid-io/olvid-bot-python-client/blob/main/olvid/listeners/GenericNotificationListener.py"
click node_listener_holder "https://github.com/olvid-io/olvid-bot-python-client/blob/main/olvid/listeners/ClientListenerHolder.py"
click node_chatbot "https://github.com/olvid-io/olvid-bot-python-client/blob/main/olvid/tools/ChatBot.py"
click node_monitoring "https://github.com/olvid-io/olvid-bot-python-client/blob/main/olvid/tools/MonitoringBot.py"
click node_delayed_tasks "https://github.com/olvid-io/olvid-bot-python-client/blob/main/olvid/tools/DelayedTasksHolder.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_cli_entry,node_cli_tree,node_domain_handlers,node_cli_helpers,node_client_selector toneBlue
class node_grpc_client,node_admin_client,node_tls_config,node_stub_holder toneAmber
class node_grpc_contracts,node_command_contracts,node_admin_contracts,node_notification_contracts,node_data_models toneMint
class node_listener_api,node_listener_base,node_listener_holder,node_chatbot,node_monitoring,node_delayed_tasks toneRose
class node_operator,node_daemon toneIndigo
```

## Components

### CLI

- [CLI entry](https://github.com/olvid-io/olvid-bot-python-client/blob/main/olvid/__main__.py): `olvid/__main__.py`
- [Command tree](https://github.com/olvid-io/olvid-bot-python-client/blob/main/olvid/cli/interactive_tree.py): `olvid/cli/interactive_tree.py`
- [Domain handlers](https://github.com/olvid-io/olvid-bot-python-client/tree/main/olvid/cli/handler): `olvid/cli/handler`
- [CLI helpers](https://github.com/olvid-io/olvid-bot-python-client/blob/main/olvid/cli/tools/cli_tools.py): `olvid/cli/tools/cli_tools.py`
- [Client selector](https://github.com/olvid-io/olvid-bot-python-client/blob/main/olvid/cli/tools/ClientSingleton.py): `olvid/cli/tools/ClientSingleton.py`

### Client and transport

- [Olvid client](https://github.com/olvid-io/olvid-bot-python-client/blob/main/olvid/core/OlvidClient.py): `olvid/core/OlvidClient.py`
- [Admin client](https://github.com/olvid-io/olvid-bot-python-client/blob/main/olvid/core/OlvidAdminClient.py): `olvid/core/OlvidAdminClient.py`
- [gRPC TLS](https://github.com/olvid-io/olvid-bot-python-client/blob/main/olvid/core/GrpcTlsConfiguration.py): `olvid/core/GrpcTlsConfiguration.py`
- [Stub holder](https://github.com/olvid-io/olvid-bot-python-client/blob/main/olvid/core/StubHolder.py): `olvid/core/StubHolder.py`

### API contracts

- [gRPC stubs](https://github.com/olvid-io/olvid-bot-python-client/tree/main/olvid/protobuf): `olvid/protobuf`
- [Command contracts](https://github.com/olvid-io/olvid-bot-python-client/blob/main/olvid/internal/commands/commands.py): `olvid/internal/commands/commands.py`
- [Admin contracts](https://github.com/olvid-io/olvid-bot-python-client/blob/main/olvid/internal/admin/admin.py): `olvid/internal/admin/admin.py`
- [Notification contracts](https://github.com/olvid-io/olvid-bot-python-client/blob/main/olvid/internal/notifications/notifications.py): `olvid/internal/notifications/notifications.py`
- [Data models](https://github.com/olvid-io/olvid-bot-python-client/blob/main/olvid/datatypes/datatypes.py): `olvid/datatypes/datatypes.py`

### Events and tools

- [Listener API](https://github.com/olvid-io/olvid-bot-python-client/blob/main/olvid/listeners/ListenersImplementation.py): `olvid/listeners/ListenersImplementation.py`
- [Generic listener](https://github.com/olvid-io/olvid-bot-python-client/blob/main/olvid/listeners/GenericNotificationListener.py): `olvid/listeners/GenericNotificationListener.py`
- [Listener holder](https://github.com/olvid-io/olvid-bot-python-client/blob/main/olvid/listeners/ClientListenerHolder.py): `olvid/listeners/ClientListenerHolder.py`
- [Chatbot helper](https://github.com/olvid-io/olvid-bot-python-client/blob/main/olvid/tools/ChatBot.py): `olvid/tools/ChatBot.py`
- [Monitoring helper](https://github.com/olvid-io/olvid-bot-python-client/blob/main/olvid/tools/MonitoringBot.py): `olvid/tools/MonitoringBot.py`
- [Delayed tasks](https://github.com/olvid-io/olvid-bot-python-client/blob/main/olvid/tools/DelayedTasksHolder.py): `olvid/tools/DelayedTasksHolder.py`

### Other components

- **Operator**
- **Olvid daemon**

## Connections

- Operator → CLI entry: runs (evidence: `olvid/__main__.py`)
- CLI entry → Command tree: dispatches to (evidence: `olvid/__main__.py`)
- Command tree → Domain handlers: registers (evidence: `olvid/cli/interactive_tree.py`)
- Domain handlers → Client selector: selects client (evidence: `olvid/cli/handler/group_tree.py`)
- Domain handlers → CLI helpers: formats results (evidence: `olvid/cli/handler/storage_tree.py`)
- Client selector → Admin client: creates default (evidence: `olvid/cli/tools/ClientSingleton.py`)
- Client selector → Olvid client: creates impersonated (evidence: `olvid/cli/tools/ClientSingleton.py`)
- Olvid client → Stub holder: uses stubs (evidence: `olvid/core/OlvidClient.py`)
- Admin client → Stub holder: uses stubs (evidence: `olvid/core/OlvidAdminClient.py`)
- Olvid client → Data models: uses types (evidence: `olvid/core/OlvidClient.py`)
- Admin client → Data models: uses types (evidence: `olvid/core/OlvidAdminClient.py`)
- Admin client → gRPC TLS: configures TLS (evidence: `olvid/core/OlvidAdminClient.py`)
- Stub holder → Command contracts: loads contracts (evidence: `olvid/core/StubHolder.py`)
- Stub holder → Admin contracts: loads contracts (evidence: `olvid/core/StubHolder.py`)
- Stub holder → Notification contracts: loads contracts (evidence: `olvid/core/StubHolder.py`)
- gRPC stubs → Olvid daemon: calls gRPC (evidence: `README.md`)
- Olvid client → Olvid daemon: accesses RPCs (evidence: `README.md`)
- Olvid client → Listener holder: manages listeners (evidence: `olvid/core/OlvidClient.py`)
- Listener API → Generic listener: extends (evidence: `olvid/listeners/ListenersImplementation.py`)
- Listener holder → Generic listener: creates iterators (evidence: `olvid/listeners/ClientListenerHolder.py`)
- Listener holder → Olvid client: dispatches callbacks (evidence: `olvid/listeners/ClientListenerHolder.py`)
- Chatbot helper → Olvid client: subclasses (evidence: `olvid/tools/ChatBot.py`)
- Chatbot helper → Listener API: uses listeners (evidence: `olvid/tools/ChatBot.py`)
- Monitoring helper → Olvid client: uses client (evidence: `olvid/tools/MonitoringBot.py`)
- Delayed tasks → Olvid daemon: schedules tasks
