# avito-tech/go-transaction-manager architecture

> Architecture diagram of the GitHub repository avito-tech/go-transaction-manager, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/avito-tech/go-transaction-manager
- Repository: https://github.com/avito-tech/go-transaction-manager

## Overview

1. **What this repository is**
   - This is a multi-module Go library for transaction management, not an application.
   - The root repo contains the shared orchestration layer plus a set of database-specific driver adapters.
   - `go.work` ties the modules together for local development and testing.

2. **Core abstraction layer: `trm`**
   - `trm/` is the central package that defines the transaction-manager API, context propagation, and manager behavior.
   - It is the boundary that application code depends on: repositories receive a `context.Context`, and transaction state is carried through that context.
   - Key responsibilities include transaction lifecycle coordination, settings, error handling, and nested transaction chaining.

3. **Transaction orchestration flow**
   - Application code calls a manager, typically through `manager.Do(...)`.
   - The manager starts or reuses a transaction, injects it into context, executes user code, then commits or rolls back based on the result.
   - Repository methods do not need to know whether they are running inside a transaction; they resolve the active transaction from context or fall back to the base connection.

4. **Context as the integration boundary**
   - The `trm/context` package defines the keys and helpers used to store transaction-related values in `context.Context`.
   - Driver packages provide their own context getters so repositories can retrieve the correct transaction object for that backend.
   - This design makes the transaction manager backend-agnostic while keeping context lookup consistent.

5. **Driver packages: backend adapters**
   - `drivers/` contains one module per supported backend:
     - `sql` for `database/sql`
     - `sqlx` for `jmoiron/sqlx`
     - `gorm` for GORM
     - `mongo` for the MongoDB Go driver
     - `goredis8` for go-redis
     - `pgxv4` and `pgxv5` for pgx
   - Each driver wraps the backend’s native transaction/session type and adapts it to the shared manager contracts.
   - This is the main extensibility boundary: adding another database means adding another driver module, not changing the core manager.

6. **Common driver pattern**
   - Most drivers contain:
     - a `factory` that creates a transaction manager for that backend,
     - `context` helpers to extract the current transaction,
     - `transaction` logic for commit/rollback semantics,
     - `settings` for backend-specific behavior.
   - The `contract.go` files in some drivers define the interface expected from the underlying DB/session implementation.

7. **Nested transactions and special cases**
   - The repository supports nested transaction behavior, but the mechanism varies by backend.
   - For SQL-based drivers, nested behavior can use savepoints; `drivers/sql/mock/savepoint.go` and `drivers/sql/savepoint.go` show this concern explicitly.
   - The root README also calls out `ChainedMW` for coordinating nested transactions across different managers, which matters when one service operation touches multiple databases.

8. **Repository usage model**
   - The intended consumer pattern is “repository + context + manager.”
   - Repositories are written against a DB handle plus a driver-specific context getter; they select either the active transaction or the base DB connection from context.
   - This keeps business logic clean and makes transaction boundaries a caller concern rather than a repository concern.

9. **Testing and verification structure**
   - Each driver module has focused unit tests, goroutine-leak tests, and some integration tests where the backend requires a real database.
   - The `trm/drivers/test` package provides shared test infrastructure, including Docker Compose for database-backed integration runs.
   - The repo also includes example tests in each driver module, which double as executable documentation for the supported usage patterns.

10. **Internal benchmarks and research tooling**
   - `trm/internal/benchmark/` contains performance investigations comparing context storage strategies and measuring the overhead of transaction management.
   - These benchmarks are not runtime dependencies, but they explain design choices around context usage and overhead.
   - `trm/internal/prove_receiving_updates_without_vulnerabilities` and `trm/internal/recover_defer` look like focused correctness experiments around Go runtime behavior and error/recovery semantics.

11. **Code generation and support scripts**
   - `trm/internal/codegen/redis` suggests some generated support for Redis-related driver behavior.
   - The `sh/` directory contains repo automation for formatting, linting, dependency management, and release/tagging.
   - CI is driven by GitHub Actions, with linting and multi-version Go test coverage wired through `.github/workflows/main.yaml`.

12. **Infrastructure and external dependencies**
   - The library is built around external persistence systems rather than in-process storage: SQL databases, MongoDB, Redis, and PostgreSQL via pgx.
   - Compatibility across multiple Go versions is a deliberate architectural constraint, which is why each module has its own `go.mod` and why the repo keeps older dependency versions in some modules.
   - The architecture is therefore “core abstraction + backend adapters + context propagation,” optimized for reuse across many storage technologies.

13. **How to draw the diagram**
   - Put `trm` in the center as the orchestration core.
   - Show application/repository code calling into the manager with a context.
   - Show driver modules as adapters between the core and backend-specific clients.
   - Show context as the shared channel connecting manager and repositories.
   - Show testing/benchmarking as parallel supporting subsystems, not part of the runtime path.

Main entry points: [`trm/manager`](https://github.com/avito-tech/go-transaction-manager/tree/main/trm/manager) (Manager), [`trm/context`](https://github.com/avito-tech/go-transaction-manager/tree/main/trm/context) (Context), [`.github/workflows/main.yaml`](https://github.com/avito-tech/go-transaction-manager/blob/main/.github/workflows/main.yaml) (Automation), [`go.work`](https://github.com/avito-tech/go-transaction-manager/blob/main/go.work) (Go work)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core"]
  node_trm["TRM<br/>core package"]
  node_trm_context["Context<br/>ctx helpers"]
  node_trm_manager["Manager<br/>orchestrator"]
  node_trm_settings["Settings<br/>config"]
end

subgraph group_drivers["Drivers"]
  node_sql["SQL<br/>adapter"]
  node_sqlx["SQLX<br/>adapter"]
  node_gorm["GORM<br/>adapter"]
  node_mongo["MongoDB<br/>adapter"]
  node_pgxv4["pgx v4<br/>adapter"]
  node_pgxv5["pgx v5<br/>adapter"]
  node_goredis8["Redis<br/>adapter"]
end

subgraph group_support["Support"]
  node_test_infra["Test infra<br/>shared tests"]
  node_benchmarks["Benchmarks<br/>research tooling"]
  node_experiments["Experiments<br/>correctness labs"]
  node_codegen["Codegen<br/>generated support"]
  node_automation["Automation<br/>scripts/CI<br/>[main.yaml]"]
  node_go_work["Go work<br/>workspace<br/>[go.work]"]
end

node_consumer["Repos<br/>consumer code"]

node_consumer -->|"Do / use"| node_trm_manager
node_consumer -->|"ctx lookup"| node_trm_context
node_trm -->|"hosts"| node_trm_manager
node_trm -->|"defines"| node_trm_context
node_trm -->|"configures"| node_trm_settings
node_trm_manager -->|"injects"| node_trm_context
node_trm_manager -->|"reads"| node_trm_settings
node_trm_manager -->|"adapts via"| node_sql
node_trm_manager -->|"adapts via"| node_sqlx
node_trm_manager -->|"adapts via"| node_gorm
node_trm_manager -->|"adapts via"| node_mongo
node_trm_manager -->|"adapts via"| node_pgxv4
node_trm_manager -->|"adapts via"| node_pgxv5
node_trm_manager -->|"adapts via"| node_goredis8
node_sql -->|"reads"| node_trm_context
node_sqlx -->|"reads"| node_trm_context
node_gorm -->|"reads"| node_trm_context
node_mongo -->|"reads"| node_trm_context
node_pgxv4 -->|"reads"| node_trm_context
node_pgxv5 -->|"reads"| node_trm_context
node_goredis8 -->|"reads"| node_trm_context
node_sql -.->|"verified by"| node_test_infra
node_sqlx -.->|"verified by"| node_test_infra
node_gorm -.->|"verified by"| node_test_infra
node_mongo -.->|"verified by"| node_test_infra
node_pgxv4 -.->|"verified by"| node_test_infra
node_pgxv5 -.->|"verified by"| node_test_infra
node_goredis8 -.->|"verified by"| node_test_infra
node_trm -.->|"studied by"| node_benchmarks
node_trm -.->|"studied by"| node_experiments
node_goredis8 -.->|"supported by"| node_codegen
node_automation -.->|"builds/tests"| node_trm
node_automation -.->|"builds/tests"| node_sql
node_automation -.->|"builds/tests"| node_sqlx
node_automation -.->|"builds/tests"| node_gorm
node_automation -.->|"builds/tests"| node_mongo
node_automation -.->|"builds/tests"| node_pgxv4
node_automation -.->|"builds/tests"| node_pgxv5
node_automation -.->|"builds/tests"| node_goredis8
node_go_work -.->|"ties together"| node_trm
node_go_work -.->|"ties together"| node_sql
node_go_work -.->|"ties together"| node_sqlx
node_go_work -.->|"ties together"| node_gorm
node_go_work -.->|"ties together"| node_mongo
node_go_work -.->|"ties together"| node_pgxv4
node_go_work -.->|"ties together"| node_pgxv5
node_go_work -.->|"ties together"| node_goredis8

click node_trm "https://github.com/avito-tech/go-transaction-manager/tree/main/trm"
click node_trm_context "https://github.com/avito-tech/go-transaction-manager/tree/main/trm/context"
click node_trm_manager "https://github.com/avito-tech/go-transaction-manager/tree/main/trm/manager"
click node_trm_settings "https://github.com/avito-tech/go-transaction-manager/tree/main/trm/settings"
click node_sql "https://github.com/avito-tech/go-transaction-manager/tree/main/drivers/sql"
click node_sqlx "https://github.com/avito-tech/go-transaction-manager/tree/main/drivers/sqlx"
click node_gorm "https://github.com/avito-tech/go-transaction-manager/tree/main/drivers/gorm"
click node_mongo "https://github.com/avito-tech/go-transaction-manager/tree/main/drivers/mongo"
click node_pgxv4 "https://github.com/avito-tech/go-transaction-manager/tree/main/drivers/pgxv4"
click node_pgxv5 "https://github.com/avito-tech/go-transaction-manager/tree/main/drivers/pgxv5"
click node_goredis8 "https://github.com/avito-tech/go-transaction-manager/tree/main/drivers/goredis8"
click node_test_infra "https://github.com/avito-tech/go-transaction-manager/tree/main/trm/drivers/test"
click node_benchmarks "https://github.com/avito-tech/go-transaction-manager/tree/main/trm/internal/benchmark"
click node_experiments "https://github.com/avito-tech/go-transaction-manager/tree/main/trm/internal/prove_receiving_updates_without_vulnerabilities"
click node_codegen "https://github.com/avito-tech/go-transaction-manager/tree/main/trm/internal/codegen/redis"
click node_automation "https://github.com/avito-tech/go-transaction-manager/blob/main/.github/workflows/main.yaml"
click node_go_work "https://github.com/avito-tech/go-transaction-manager/blob/main/go.work"

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_trm,node_trm_context,node_trm_manager,node_trm_settings toneBlue
class node_sql,node_sqlx,node_gorm,node_mongo,node_pgxv4,node_pgxv5,node_goredis8 toneAmber
class node_test_infra,node_benchmarks,node_experiments,node_codegen,node_automation,node_go_work toneMint
class node_consumer toneNeutral
```

## Components

### Core

Shared transaction-manager API, context propagation, and orchestration.

- [TRM](https://github.com/avito-tech/go-transaction-manager/tree/main/trm): core package · Public transaction-manager abstraction and shared entrypoint package. · `trm`
- [Context](https://github.com/avito-tech/go-transaction-manager/tree/main/trm/context): ctx helpers · Shared context keys and helpers for storing and retrieving transaction state. · `trm/context`
- [Manager](https://github.com/avito-tech/go-transaction-manager/tree/main/trm/manager): orchestrator · Transaction lifecycle coordination, reuse, commit, rollback, and chaining. · `trm/manager`
- [Settings](https://github.com/avito-tech/go-transaction-manager/tree/main/trm/settings): config · Core transaction-manager options and defaults. · `trm/settings`

### Drivers

Backend adapters that wrap native DB/session transactions.

- [SQL](https://github.com/avito-tech/go-transaction-manager/tree/main/drivers/sql): adapter · database/sql backend adapter with savepoint support for nested transactions. · `drivers/sql`
- [SQLX](https://github.com/avito-tech/go-transaction-manager/tree/main/drivers/sqlx): adapter · sqlx backend adapter built on the shared manager contracts. · `drivers/sqlx`
- [GORM](https://github.com/avito-tech/go-transaction-manager/tree/main/drivers/gorm): adapter · GORM backend adapter wrapping ORM transactions. · `drivers/gorm`
- [MongoDB](https://github.com/avito-tech/go-transaction-manager/tree/main/drivers/mongo): adapter · MongoDB backend adapter for session and transaction handling. · `drivers/mongo`
- [pgx v4](https://github.com/avito-tech/go-transaction-manager/tree/main/drivers/pgxv4): adapter · pgx v4 adapter for PostgreSQL transactions. · `drivers/pgxv4`
- [pgx v5](https://github.com/avito-tech/go-transaction-manager/tree/main/drivers/pgxv5): adapter · pgx v5 adapter for PostgreSQL transactions. · `drivers/pgxv5`
- [Redis](https://github.com/avito-tech/go-transaction-manager/tree/main/drivers/goredis8): adapter · go-redis v8 adapter for transactional Redis workflows. · `drivers/goredis8`

### Support

Testing, benchmarks, experiments, and repo automation.

- [Test infra](https://github.com/avito-tech/go-transaction-manager/tree/main/trm/drivers/test): shared tests · Cross-driver test utilities, Docker Compose setup, and mock implementations. · `trm/drivers/test`
- [Benchmarks](https://github.com/avito-tech/go-transaction-manager/tree/main/trm/internal/benchmark): research tooling · Performance experiments for context storage and transaction overhead. · `trm/internal/benchmark`
- [Experiments](https://github.com/avito-tech/go-transaction-manager/tree/main/trm/internal/prove_receiving_updates_without_vulnerabilities): correctness labs · Focused proof and recovery experiments around Go behavior and error handling. · `trm/internal/prove_receiving_updates_without_vulnerabilities`
- [Codegen](https://github.com/avito-tech/go-transaction-manager/tree/main/trm/internal/codegen/redis): generated support · Internal generation support for backend-specific helpers. · `trm/internal/codegen/redis`
- [Automation](https://github.com/avito-tech/go-transaction-manager/blob/main/.github/workflows/main.yaml): scripts/CI · Formatting, linting, testing, release scripts, and GitHub Actions workflows. · `.github/workflows/main.yaml`
- [Go work](https://github.com/avito-tech/go-transaction-manager/blob/main/go.work): workspace · Workspace file tying the repository modules together for local development. · `go.work`

### Other components

- **Repos**: consumer code · Application repositories and services that call into the manager with a context.

## Connections

- Repos → Manager: Do / use · Repositories call the manager with a context and business function.
- Repos → Context: ctx lookup · Repositories resolve the active transaction from context.
- TRM → Manager: hosts · The root package exposes manager-oriented transaction APIs.
- TRM → Context: defines · Shared context keys and helpers live under the context boundary.
- TRM → Settings: configures · Core settings shape transaction behavior and defaults.
- Manager → Context: injects · Manager writes transaction state into context for downstream use.
- Manager → Settings: reads · Manager behavior is driven by core settings.
- Manager → SQL: adapts via · Manager coordinates SQL backend transactions through driver adapters.
- Manager → SQLX: adapts via · Manager coordinates sqlx backend transactions through driver adapters.
- Manager → GORM: adapts via · Manager coordinates GORM backend transactions through driver adapters.
- Manager → MongoDB: adapts via · Manager coordinates MongoDB backend sessions and transactions through driver adapters.
- Manager → pgx v4: adapts via · Manager coordinates pgx v4 backend transactions through driver adapters.
- Manager → pgx v5: adapts via · Manager coordinates pgx v5 backend transactions through driver adapters.
- Manager → Redis: adapts via · Manager coordinates Redis transactional behavior through driver adapters.
- SQL → Context: reads · SQL repositories and helpers extract transaction state from context.
- SQLX → Context: reads · SQLX repositories and helpers extract transaction state from context.
- GORM → Context: reads · GORM repositories and helpers extract transaction state from context.
- MongoDB → Context: reads · MongoDB repositories and helpers extract transaction state from context.
- pgx v4 → Context: reads · pgx v4 repositories and helpers extract transaction state from context.
- pgx v5 → Context: reads · pgx v5 repositories and helpers extract transaction state from context.
- Redis → Context: reads · Redis repositories and helpers extract transaction state from context.
- SQL → Test infra: verified by · SQL driver tests share backend and cleanup infrastructure.
- SQLX → Test infra: verified by · SQLX driver tests share backend and cleanup infrastructure.
- GORM → Test infra: verified by · GORM driver tests share backend and cleanup infrastructure.
- MongoDB → Test infra: verified by · MongoDB driver tests share backend and cleanup infrastructure.
- pgx v4 → Test infra: verified by · pgx v4 driver tests share backend and cleanup infrastructure.
- pgx v5 → Test infra: verified by · pgx v5 driver tests share backend and cleanup infrastructure.
- Redis → Test infra: verified by · Redis driver tests share backend and cleanup infrastructure.
- TRM → Benchmarks: studied by · Benchmarks explain context and manager overhead tradeoffs.
- TRM → Experiments: studied by · Internal experiments probe correctness and recovery behavior.
- Redis → Codegen: supported by · Redis driver support includes internal generated helpers.
- Automation → TRM: builds/tests · CI and scripts format, lint, and test the core module.
- Automation → SQL: builds/tests · CI and scripts format, lint, and test the SQL driver.
- Automation → SQLX: builds/tests · CI and scripts format, lint, and test the SQLX driver.
- Automation → GORM: builds/tests · CI and scripts format, lint, and test the GORM driver.
- Automation → MongoDB: builds/tests · CI and scripts format, lint, and test the Mongo driver.
- Automation → pgx v4: builds/tests · CI and scripts format, lint, and test the pgx v4 driver.
- Automation → pgx v5: builds/tests · CI and scripts format, lint, and test the pgx v5 driver.
- Automation → Redis: builds/tests · CI and scripts format, lint, and test the Redis driver.
- Go work → TRM: ties together · Workspace links the core module for local development.
- Go work → SQL: ties together · Workspace links the SQL driver module for local development.
- Go work → SQLX: ties together · Workspace links the SQLX driver module for local development.
- Go work → GORM: ties together · Workspace links the GORM driver module for local development.
- Go work → MongoDB: ties together · Workspace links the Mongo driver module for local development.
- Go work → pgx v4: ties together · Workspace links the pgx v4 driver module for local development.
- Go work → pgx v5: ties together · Workspace links the pgx v5 driver module for local development.
- Go work → Redis: ties together · Workspace links the Redis driver module for local development.