avito-tech/go-transaction-manager

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.