# foad-khab/baleclient architecture

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

- Interactive diagram: https://gitdiagram.com/foad-khab/baleclient
- Repository: https://github.com/foad-khab/baleclient

## Overview

BaleClient is an asynchronous Python client library for Bale Messenger. A consumer creates a Client, authenticates or loads a session, invokes domain operations, and receives parsed response models. The client coordinates the HTTP session and method dispatch; domain methods describe operations across messaging, groups, users, files, presence, and other Bale services. The README documents asynchronous use and parsing/error-handling improvements. Source excerpts are partial, so links not evidenced by those excerpts, the SOURCE INDEX, or the README are omitted.

Main entry points: [`baleclient/client/client.py`](https://github.com/foad-khab/baleclient/blob/main/baleclient/client/client.py) (Client API), [`baleclient/types`](https://github.com/foad-khab/baleclient/tree/main/baleclient/types) (Domain models), [`baleclient/client/session/aiohttp.py`](https://github.com/foad-khab/baleclient/blob/main/baleclient/client/session/aiohttp.py) (HTTP sessions), [`baleclient/utils/grpc_post.py`](https://github.com/foad-khab/baleclient/blob/main/baleclient/utils/grpc_post.py) (Request encoding)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client and transport"]
  node_client_api["Client API<br/>[client.py]"]
  node_auth["Authentication<br/>[auth_cli.py]"]
  node_session["HTTP sessions<br/>[aiohttp.py]"]
  node_grpc["Request encoding<br/>[grpc_post.py]"]
end

subgraph group_operations["Bale operations"]
  node_message_ops["Messaging"]
  node_group_ops["Group management"]
  node_user_ops["User and contacts"]
  node_file_ops["File operations"]
  node_presence_ops["Presence<br/>[typing.py]"]
  node_other_ops["Other Bale services"]
end

subgraph group_models["Protocol models"]
  node_domain_models["Domain models"]
  node_response_models["Response models"]
end

subgraph group_events["Events and filters"]
  node_dispatcher["Dispatcher<br/>[dispatcher.py]"]
  node_router["Event router<br/>[router.py]"]
  node_handlers["Handlers and filters<br/>[handler.py]"]
  node_filters["Filter library"]
end

node_consumer(("Client consumer"))
node_bale{{"Bale API"}}

node_consumer -->|"creates and calls"| node_client_api
node_client_api -->|"delegates authentication"| node_auth
node_client_api -->|"creates and uses"| node_session
node_client_api -->|"uses request helper"| node_grpc
node_client_api -->|"dispatches operations"| node_message_ops
node_client_api -->|"dispatches operations"| node_group_ops
node_client_api -->|"dispatches operations"| node_user_ops
node_client_api -->|"dispatches operations"| node_file_ops
node_client_api -->|"dispatches operations"| node_presence_ops
node_client_api -->|"dispatches operations"| node_other_ops
node_client_api -->|"configures dispatcher"| node_dispatcher
node_session -.->|"sends API requests"| node_bale
node_grpc -.->|"encodes requests"| node_bale
node_message_ops -.->|"uses domain data"| node_domain_models
node_group_ops -.->|"uses domain data"| node_domain_models
node_user_ops -.->|"uses domain data"| node_domain_models
node_file_ops -.->|"uses domain data"| node_domain_models
node_presence_ops -->|"uses peer data"| node_domain_models
node_domain_models -.->|"provides parsed data"| node_response_models
node_dispatcher -->|"routes events"| node_router
node_router -->|"registers handlers"| node_handlers
node_handlers -->|"evaluates filters"| node_filters

click node_client_api "https://github.com/foad-khab/baleclient/blob/main/baleclient/client/client.py"
click node_auth "https://github.com/foad-khab/baleclient/blob/main/baleclient/client/auth_cli.py"
click node_session "https://github.com/foad-khab/baleclient/blob/main/baleclient/client/session/aiohttp.py"
click node_grpc "https://github.com/foad-khab/baleclient/blob/main/baleclient/utils/grpc_post.py"
click node_message_ops "https://github.com/foad-khab/baleclient/tree/main/baleclient/methods/messaging"
click node_group_ops "https://github.com/foad-khab/baleclient/tree/main/baleclient/methods/groups"
click node_user_ops "https://github.com/foad-khab/baleclient/tree/main/baleclient/methods/user"
click node_file_ops "https://github.com/foad-khab/baleclient/tree/main/baleclient/methods/files"
click node_presence_ops "https://github.com/foad-khab/baleclient/blob/main/baleclient/methods/presence/typing.py"
click node_other_ops "https://github.com/foad-khab/baleclient/tree/main/baleclient/methods"
click node_domain_models "https://github.com/foad-khab/baleclient/tree/main/baleclient/types"
click node_response_models "https://github.com/foad-khab/baleclient/tree/main/baleclient/types/responses"
click node_dispatcher "https://github.com/foad-khab/baleclient/blob/main/baleclient/dispatcher/dispatcher.py"
click node_router "https://github.com/foad-khab/baleclient/blob/main/baleclient/dispatcher/router.py"
click node_handlers "https://github.com/foad-khab/baleclient/blob/main/baleclient/dispatcher/event/handler.py"
click node_filters "https://github.com/foad-khab/baleclient/tree/main/baleclient/filters"

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_client_api,node_auth,node_session,node_grpc,node_consumer toneBlue
class node_message_ops,node_group_ops,node_user_ops,node_file_ops,node_presence_ops,node_other_ops toneAmber
class node_domain_models,node_response_models,node_bale toneMint
class node_dispatcher,node_router,node_handlers,node_filters toneRose
```

## Components

### Client and transport

- [Client API](https://github.com/foad-khab/baleclient/blob/main/baleclient/client/client.py): `baleclient/client/client.py`
- [Authentication](https://github.com/foad-khab/baleclient/blob/main/baleclient/client/auth_cli.py): `baleclient/client/auth_cli.py`
- [HTTP sessions](https://github.com/foad-khab/baleclient/blob/main/baleclient/client/session/aiohttp.py): `baleclient/client/session/aiohttp.py`
- [Request encoding](https://github.com/foad-khab/baleclient/blob/main/baleclient/utils/grpc_post.py): `baleclient/utils/grpc_post.py`

### Bale operations

- [Messaging](https://github.com/foad-khab/baleclient/tree/main/baleclient/methods/messaging): `baleclient/methods/messaging`
- [Group management](https://github.com/foad-khab/baleclient/tree/main/baleclient/methods/groups): `baleclient/methods/groups`
- [User and contacts](https://github.com/foad-khab/baleclient/tree/main/baleclient/methods/user): `baleclient/methods/user`
- [File operations](https://github.com/foad-khab/baleclient/tree/main/baleclient/methods/files): `baleclient/methods/files`
- [Presence](https://github.com/foad-khab/baleclient/blob/main/baleclient/methods/presence/typing.py): `baleclient/methods/presence/typing.py`
- [Other Bale services](https://github.com/foad-khab/baleclient/tree/main/baleclient/methods): `baleclient/methods`

### Protocol models

- [Domain models](https://github.com/foad-khab/baleclient/tree/main/baleclient/types): `baleclient/types`
- [Response models](https://github.com/foad-khab/baleclient/tree/main/baleclient/types/responses): `baleclient/types/responses`

### Events and filters

- [Dispatcher](https://github.com/foad-khab/baleclient/blob/main/baleclient/dispatcher/dispatcher.py): `baleclient/dispatcher/dispatcher.py`
- [Event router](https://github.com/foad-khab/baleclient/blob/main/baleclient/dispatcher/router.py): `baleclient/dispatcher/router.py`
- [Handlers and filters](https://github.com/foad-khab/baleclient/blob/main/baleclient/dispatcher/event/handler.py): `baleclient/dispatcher/event/handler.py`
- [Filter library](https://github.com/foad-khab/baleclient/tree/main/baleclient/filters): `baleclient/filters`

### Other components

- **Client consumer**
- **Bale API**

## Connections

- Client consumer → Client API: creates and calls
- Client API → Authentication: delegates authentication (evidence: `baleclient/client/client.py`)
- Client API → HTTP sessions: creates and uses (evidence: `baleclient/client/client.py`)
- Client API → Request encoding: uses request helper (evidence: `baleclient/client/client.py`)
- Client API → Messaging: dispatches operations
- Client API → Group management: dispatches operations
- Client API → User and contacts: dispatches operations
- Client API → File operations: dispatches operations
- Client API → Presence: dispatches operations (evidence: `baleclient/client/client.py`)
- Client API → Other Bale services: dispatches operations (evidence: `baleclient/methods/__init__.py`)
- Client API → Dispatcher: configures dispatcher (evidence: `baleclient/client/client.py`)
- HTTP sessions → Bale API: sends API requests
- Request encoding → Bale API: encodes requests
- Messaging → Domain models: uses domain data
- Group management → Domain models: uses domain data (evidence: `baleclient/methods/groups/get_group_preview.py`)
- User and contacts → Domain models: uses domain data (evidence: `baleclient/methods/user/search_contact.py`)
- File operations → Domain models: uses domain data
- Presence → Domain models: uses peer data (evidence: `baleclient/methods/presence/typing.py`)
- Domain models → Response models: provides parsed data (evidence: `baleclient/types/responses/__init__.py`)
- Dispatcher → Event router: routes events (evidence: `baleclient/dispatcher/dispatcher.py`)
- Event router → Handlers and filters: registers handlers (evidence: `baleclient/dispatcher/router.py`)
- Handlers and filters → Filter library: evaluates filters (evidence: `baleclient/dispatcher/event/handler.py`)