# hussein-awala/async-batcher architecture

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

- Interactive diagram: https://gitdiagram.com/hussein-awala/async-batcher
- Repository: https://github.com/hussein-awala/async-batcher

## Overview

AsyncBatcher is an async Python library that collects concurrent requests into bounded batches and routes each result back to its caller. The main flow is request submission, queue admission and batch dispatch, backend processing, then per-request outcomes; bounded maps, grouped batching and coalescing extend how work is submitted. Adapters cover databases, streams, messaging, vector storage and prediction models. The graph reflects README capabilities and shown source/index relationships; unsampled subsystem links are omitted or marked unverified rather than inferred from names.

Main entry points: [`async_batcher/batcher.py`](https://github.com/hussein-awala/async-batcher/blob/main/async_batcher/batcher.py) (Batch dispatcher), [`async_batcher/aws`](https://github.com/hussein-awala/async-batcher/tree/main/async_batcher/aws) (AWS stream adapters), [`async_batcher/grouped.py`](https://github.com/hussein-awala/async-batcher/blob/main/async_batcher/grouped.py) (Grouped batching), [`async_batcher/coalescing.py`](https://github.com/hussein-awala/async-batcher/blob/main/async_batcher/coalescing.py) (In-flight coalescing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Batching core"]
  node_engine["Batch dispatcher<br/>[batcher.py]"]
  node_options["Batch options<br/>[_options.py]"]
  node_errors["Core errors<br/>[exceptions.py]"]
  node_callable["Callable wrapper<br/>[callable.py]"]
end

subgraph group_submission["Submission patterns"]
  node_maps["Bounded maps<br/>[map.py]"]
  node_groups["Grouped batching<br/>[grouped.py]"]
  node_coalesce["In-flight coalescing<br/>[coalescing.py]"]
end

subgraph group_adapters["Backend adapters"]
  node_awsdb["DynamoDB adapter"]
  node_awsstreams["AWS stream adapters"]
  node_kafka["Kafka producer<br/>[producer.py]"]
  node_sqlalchemy["SQLAlchemy adapter<br/>[write.py]"]
  node_scylla["ScyllaDB adapter<br/>[update.py]"]
  node_mongo["MongoDB adapter<br/>[write.py]"]
  node_pinecone["Pinecone vectors<br/>[vectors.py]"]
  node_models["Prediction models"]
end

subgraph group_operations["Operations"]
  node_telemetry["Batch telemetry<br/>[observability.py]"]
end

node_caller(("Async callers"))

node_caller -->|"submits requests"| node_engine
node_engine -->|"creates wrapper"| node_callable
node_engine -->|"uses mapping"| node_maps
node_engine -->|"uses options"| node_options
node_engine -->|"emits events"| node_telemetry
node_engine -.->|"raises errors"| node_errors
node_caller -->|"streams inputs"| node_maps
node_caller -->|"groups requests"| node_groups
node_caller -->|"shares requests"| node_coalesce
node_groups -->|"owns batchers"| node_engine
node_coalesce -->|"submits work"| node_engine
node_awsstreams -->|"extends batching"| node_engine
node_awsstreams -->|"splits and retries"| node_awsstreams
node_awsdb -.->|"extends batching"| node_engine
node_kafka -->|"extends batching"| node_engine
node_sqlalchemy -.->|"extends batching"| node_engine
node_scylla -.->|"extends batching"| node_engine
node_mongo -->|"extends batching"| node_engine
node_pinecone -->|"extends batching"| node_engine
node_models -.->|"extends batching"| node_engine

click node_engine "https://github.com/hussein-awala/async-batcher/blob/main/async_batcher/batcher.py"
click node_options "https://github.com/hussein-awala/async-batcher/blob/main/async_batcher/_options.py"
click node_errors "https://github.com/hussein-awala/async-batcher/blob/main/async_batcher/exceptions.py"
click node_callable "https://github.com/hussein-awala/async-batcher/blob/main/async_batcher/callable.py"
click node_maps "https://github.com/hussein-awala/async-batcher/blob/main/async_batcher/map.py"
click node_groups "https://github.com/hussein-awala/async-batcher/blob/main/async_batcher/grouped.py"
click node_coalesce "https://github.com/hussein-awala/async-batcher/blob/main/async_batcher/coalescing.py"
click node_telemetry "https://github.com/hussein-awala/async-batcher/blob/main/async_batcher/observability.py"
click node_awsdb "https://github.com/hussein-awala/async-batcher/tree/main/async_batcher/aws/dynamodb"
click node_awsstreams "https://github.com/hussein-awala/async-batcher/tree/main/async_batcher/aws"
click node_kafka "https://github.com/hussein-awala/async-batcher/blob/main/async_batcher/kafka/producer.py"
click node_sqlalchemy "https://github.com/hussein-awala/async-batcher/blob/main/async_batcher/sqlalchemy/write.py"
click node_scylla "https://github.com/hussein-awala/async-batcher/blob/main/async_batcher/scylladb/update.py"
click node_mongo "https://github.com/hussein-awala/async-batcher/blob/main/async_batcher/mongodb/write.py"
click node_pinecone "https://github.com/hussein-awala/async-batcher/blob/main/async_batcher/pinecone/vectors.py"
click node_models "https://github.com/hussein-awala/async-batcher/tree/main/async_batcher/ml"

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_engine,node_options,node_errors,node_callable toneBlue
class node_maps,node_groups,node_coalesce toneAmber
class node_awsdb,node_awsstreams,node_kafka,node_sqlalchemy,node_scylla,node_mongo,node_pinecone,node_models toneMint
class node_telemetry toneRose
class node_caller toneIndigo
```

## Components

### Batching core

- [Batch dispatcher](https://github.com/hussein-awala/async-batcher/blob/main/async_batcher/batcher.py): `async_batcher/batcher.py`
- [Batch options](https://github.com/hussein-awala/async-batcher/blob/main/async_batcher/_options.py): `async_batcher/_options.py`
- [Core errors](https://github.com/hussein-awala/async-batcher/blob/main/async_batcher/exceptions.py): `async_batcher/exceptions.py`
- [Callable wrapper](https://github.com/hussein-awala/async-batcher/blob/main/async_batcher/callable.py): `async_batcher/callable.py`

### Submission patterns

- [Bounded maps](https://github.com/hussein-awala/async-batcher/blob/main/async_batcher/map.py): `async_batcher/map.py`
- [Grouped batching](https://github.com/hussein-awala/async-batcher/blob/main/async_batcher/grouped.py): `async_batcher/grouped.py`
- [In-flight coalescing](https://github.com/hussein-awala/async-batcher/blob/main/async_batcher/coalescing.py): `async_batcher/coalescing.py`

### Backend adapters

- [DynamoDB adapter](https://github.com/hussein-awala/async-batcher/tree/main/async_batcher/aws/dynamodb): `async_batcher/aws/dynamodb`
- [AWS stream adapters](https://github.com/hussein-awala/async-batcher/tree/main/async_batcher/aws): `async_batcher/aws`
- [Kafka producer](https://github.com/hussein-awala/async-batcher/blob/main/async_batcher/kafka/producer.py): `async_batcher/kafka/producer.py`
- [SQLAlchemy adapter](https://github.com/hussein-awala/async-batcher/blob/main/async_batcher/sqlalchemy/write.py): `async_batcher/sqlalchemy/write.py`
- [ScyllaDB adapter](https://github.com/hussein-awala/async-batcher/blob/main/async_batcher/scylladb/update.py): `async_batcher/scylladb/update.py`
- [MongoDB adapter](https://github.com/hussein-awala/async-batcher/blob/main/async_batcher/mongodb/write.py): `async_batcher/mongodb/write.py`
- [Pinecone vectors](https://github.com/hussein-awala/async-batcher/blob/main/async_batcher/pinecone/vectors.py): `async_batcher/pinecone/vectors.py`
- [Prediction models](https://github.com/hussein-awala/async-batcher/tree/main/async_batcher/ml): `async_batcher/ml`

### Operations

- [Batch telemetry](https://github.com/hussein-awala/async-batcher/blob/main/async_batcher/observability.py): `async_batcher/observability.py`

### Other components

- **Async callers**

## Connections

- Async callers → Batch dispatcher: submits requests (evidence: `README.md`)
- Batch dispatcher → Callable wrapper: creates wrapper (evidence: `async_batcher/batcher.py`)
- Batch dispatcher → Bounded maps: uses mapping (evidence: `async_batcher/batcher.py`)
- Batch dispatcher → Batch options: uses options (evidence: `async_batcher/batcher.py`)
- Batch dispatcher → Batch telemetry: emits events (evidence: `async_batcher/batcher.py`)
- Batch dispatcher → Core errors: raises errors (evidence: `async_batcher/batcher.py`)
- Async callers → Bounded maps: streams inputs (evidence: `README.md`)
- Async callers → Grouped batching: groups requests (evidence: `README.md`)
- Async callers → In-flight coalescing: shares requests (evidence: `README.md`)
- Grouped batching → Batch dispatcher: owns batchers (evidence: `async_batcher/grouped.py`)
- In-flight coalescing → Batch dispatcher: submits work (evidence: `async_batcher/coalescing.py`)
- AWS stream adapters → Batch dispatcher: extends batching (evidence: `async_batcher/aws/kinesis/write.py`)
- AWS stream adapters → AWS stream adapters: splits and retries (evidence: `async_batcher/aws/kinesis/write.py`)
- DynamoDB adapter → Batch dispatcher: extends batching (evidence: `async_batcher/aws/dynamodb/get.py`)
- Kafka producer → Batch dispatcher: extends batching (evidence: `async_batcher/kafka/producer.py`)
- SQLAlchemy adapter → Batch dispatcher: extends batching (evidence: `async_batcher/sqlalchemy/write.py`)
- ScyllaDB adapter → Batch dispatcher: extends batching (evidence: `async_batcher/scylladb/update.py`)
- MongoDB adapter → Batch dispatcher: extends batching (evidence: `async_batcher/mongodb/write.py`)
- Pinecone vectors → Batch dispatcher: extends batching (evidence: `async_batcher/pinecone/vectors.py`)
- Prediction models → Batch dispatcher: extends batching (evidence: `async_batcher/ml/sklearn/model.py`)