# corridor/sqlalchemy-history architecture

> Architecture diagram of the GitHub repository corridor/sqlalchemy-history, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/corridor/sqlalchemy-history
- Repository: https://github.com/corridor/sqlalchemy-history

## Overview

1. **What this repository is**
   - `sqlalchemy-history` is a SQLAlchemy ORM extension for audit/version tracking.
   - It is a library, not an application: user models opt in with `__versioned__`, and the package injects history tables, transaction records, and version-aware relationships.

2. **Public integration boundary**
   - The main entry point is the package root (`sqlalchemy_history/__init__.py`) plus a `make_versioned(...)`-style setup API described in the README.
   - The user’s application must call versioning setup before mapper configuration, then define normal SQLAlchemy models with versioning metadata.

3. **Core orchestration layer**
   - `factory.py`, `manager.py`, and `unit_of_work.py` appear to coordinate the runtime lifecycle of versioning.
   - This layer is the bridge between SQLAlchemy mapper/session events and the internal history machinery: it decides what gets tracked, when history rows are produced, and how transactions are grouped.

4. **Schema and model generation**
   - `table_builder.py`, `model_builder.py`, `builder.py`, and `schema.py` generate the versioning infrastructure around user models.
   - They create the companion version tables, transaction tables, and mapped history classes that mirror the original model structure.
   - `relationship_builder.py` handles relationship-specific version metadata so object graphs can be reconstructed over time.

5. **How change data is captured**
   - `operation.py`, `transaction.py`, `fetcher.py`, and `version.py` represent the captured audit data and the mechanics of persisting it.
   - The flow is: ORM mutation happens on a versioned object, the session flush/commit cycle is observed, changed attributes are detected, and a version row plus transaction metadata are written.

6. **Attribute and query reconstruction**
   - `expression_reflector.py` and `utils.py` support translating SQLAlchemy expressions and object state into history-aware equivalents.
   - This is what enables temporal querying and “what did this object look like at transaction X?” style access.

7. **Reversion subsystem**
   - `reverter.py` is the rollback/restore engine.
   - It uses the stored version history to restore scalar fields and related objects, including cases where the original object was deleted.
   - This makes revert a first-class workflow, not just a read-only audit log.

8. **Plugin architecture**
   - `plugins/base.py` defines the extension contract, and the concrete plugins are small, focused behaviors:
     - `activity.py` for activity/user context,
     - `null_delete.py` for delete handling semantics,
     - `property_mod_tracker.py` for per-field modification tracking,
     - `transaction_changes.py` for transaction-level change aggregation,
     - `transaction_meta.py` for extra transaction metadata.
   - The design suggests composable feature slices rather than one monolithic auditing path.

9. **Async support boundary**
   - The README and `tests/sqlalchemy_async/` show explicit async support.
   - The versioning core is designed to work with both sync SQLAlchemy sessions and async engines/sessions, with querying and revert behavior preserved in async workflows.

10. **Database and migration concerns**
   - The test matrix and docs reference SQLite, PostgreSQL, MSSQL, Oracle, and Alembic.
   - This implies the architecture is intentionally database-portable and avoids backend-specific assumptions where possible.
   - `tests/databases/` contains docker-compose files for cross-database verification.

11. **Versioning strategies and compatibility**
   - `tests/schema/` and `docs/schema.md`, `docs/transactions.md`, `docs/revert.md`, and `docs/queries.md` indicate multiple internal concerns: schema layout, transaction semantics, and history querying.
   - The presence of `tests/test_validity_strategy.py` suggests the library supports at least one explicit strategy for deciding version validity windows.

12. **Behavioral coverage in tests**
   - The tests are organized around architecture boundaries: builders, plugins, relationships, inheritance, revert, schema, async, and reported bugs.
   - That separation reflects the main subsystems of the library and shows which areas are considered stable public behavior.

13. **Tooling and delivery**
   - The repo uses Ruff, pre-commit, MkDocs, and GitHub Actions for CI/docs/release automation.
   - These are supporting concerns only; they don’t affect runtime architecture, but they explain how the library is validated and published.

14. **Mental model for a diagram**
   - At the center is the user’s SQLAlchemy model/session layer.
   - Around it sits the versioning manager and unit-of-work pipeline, which observes ORM events, builds version tables/models, stores transaction snapshots, and exposes history/revert/query APIs.
   - Plugins extend that core pipeline, while async support and cross-database compatibility constrain the whole design.

Main entry points: [`sqlalchemy_history/version.py`](https://github.com/corridor/sqlalchemy-history/blob/main/sqlalchemy_history/version.py) (Version), [`sqlalchemy_history/plugins/base.py`](https://github.com/corridor/sqlalchemy-history/blob/main/sqlalchemy_history/plugins/base.py) (Plugin Base), [`sqlalchemy_history/builder.py`](https://github.com/corridor/sqlalchemy-history/blob/main/sqlalchemy_history/builder.py) (Builder), [`sqlalchemy_history/transaction.py`](https://github.com/corridor/sqlalchemy-history/blob/main/sqlalchemy_history/transaction.py) (Transaction)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public_api["Public API"]
  node_sqlalchemy_history___init__["Package API<br/>entrypoint<br/>[__init__.py]"]
end

subgraph group_runtime_core["Runtime Core"]
  node_factory_py["Factory<br/>bootstrap<br/>[factory.py]"]
  node_manager_py["Manager<br/>orchestrator<br/>[manager.py]"]
  node_unit_of_work_py["Unit of Work<br/>session-flow<br/>[unit_of_work.py]"]
end

subgraph group_generation["Schema Builders"]
  node_builder_py["Builder<br/>composition<br/>[builder.py]"]
  node_schema_py["Schema<br/>[schema.py]"]
  node_table_builder_py["Table Builder<br/>table-gen<br/>[table_builder.py]"]
  node_model_builder_py["Model Builder<br/>model-gen<br/>[model_builder.py]"]
  node_relationship_builder_py["Rel Builder<br/>relationship-gen"]
end

subgraph group_history_flow["History Flow"]
  node_operation_py["Operation<br/>change-record<br/>[operation.py]"]
  node_transaction_py["Transaction<br/>audit-record<br/>[transaction.py]"]
  node_version_py["Version<br/>history-record<br/>[version.py]"]
  node_fetcher_py["Fetcher<br/>state-reader<br/>[fetcher.py]"]
  node_expression_reflector_py["Reflector<br/>query-adapter"]
  node_reverter_py["Reverter<br/>restore-engine<br/>[reverter.py]"]
  node_utils_py["Utils<br/>support<br/>[utils.py]"]
end

subgraph group_extensions["Plugins"]
  node_plugins_base_py["Plugin Base<br/>extension-contract<br/>[base.py]"]
  node_plugins_activity_py["Activity<br/>plugin<br/>[activity.py]"]
  node_plugins_null_delete_py["Null Delete<br/>plugin<br/>[null_delete.py]"]
  node_plugins_property_mod_tracker_py["Mod Tracker<br/>plugin"]
  node_plugins_transaction_changes_py["Tx Changes<br/>plugin"]
  node_plugins_transaction_meta_py["Tx Meta<br/>plugin"]
end

node_sqlalchemy_history___init__ -->|"setup API"| node_factory_py
node_factory_py -->|"builds"| node_manager_py
node_manager_py -->|"drives"| node_unit_of_work_py
node_manager_py -->|"configures"| node_builder_py
node_builder_py -->|"uses"| node_schema_py
node_builder_py -->|"creates tables"| node_table_builder_py
node_builder_py -->|"creates models"| node_model_builder_py
node_builder_py -->|"adds relations"| node_relationship_builder_py
node_table_builder_py -->|"materializes"| node_version_py
node_model_builder_py -->|"maps"| node_version_py
node_relationship_builder_py -->|"supports"| node_reverter_py
node_unit_of_work_py -->|"captures state"| node_fetcher_py
node_fetcher_py -->|"detects"| node_operation_py
node_operation_py -->|"groups into"| node_transaction_py
node_transaction_py -->|"persists"| node_version_py
node_unit_of_work_py -->|"writes"| node_version_py
node_expression_reflector_py -->|"relies on"| node_utils_py
node_expression_reflector_py -->|"adapts queries"| node_reverter_py
node_reverter_py -->|"reads history"| node_version_py
node_plugins_base_py -->|"extends"| node_plugins_activity_py
node_plugins_base_py -->|"extends"| node_plugins_null_delete_py
node_plugins_base_py -->|"extends"| node_plugins_property_mod_tracker_py
node_plugins_base_py -->|"extends"| node_plugins_transaction_changes_py
node_plugins_base_py -->|"extends"| node_plugins_transaction_meta_py
node_plugins_activity_py -->|"annotates"| node_transaction_py
node_plugins_property_mod_tracker_py -->|"flags fields"| node_version_py
node_plugins_transaction_changes_py -->|"aggregates"| node_transaction_py
node_plugins_transaction_meta_py -->|"adds metadata"| node_transaction_py
node_plugins_null_delete_py -->|"changes deletes"| node_operation_py

click node_sqlalchemy_history___init__ "https://github.com/corridor/sqlalchemy-history/blob/main/sqlalchemy_history/__init__.py"
click node_factory_py "https://github.com/corridor/sqlalchemy-history/blob/main/sqlalchemy_history/factory.py"
click node_manager_py "https://github.com/corridor/sqlalchemy-history/blob/main/sqlalchemy_history/manager.py"
click node_unit_of_work_py "https://github.com/corridor/sqlalchemy-history/blob/main/sqlalchemy_history/unit_of_work.py"
click node_builder_py "https://github.com/corridor/sqlalchemy-history/blob/main/sqlalchemy_history/builder.py"
click node_schema_py "https://github.com/corridor/sqlalchemy-history/blob/main/sqlalchemy_history/schema.py"
click node_table_builder_py "https://github.com/corridor/sqlalchemy-history/blob/main/sqlalchemy_history/table_builder.py"
click node_model_builder_py "https://github.com/corridor/sqlalchemy-history/blob/main/sqlalchemy_history/model_builder.py"
click node_relationship_builder_py "https://github.com/corridor/sqlalchemy-history/blob/main/sqlalchemy_history/relationship_builder.py"
click node_operation_py "https://github.com/corridor/sqlalchemy-history/blob/main/sqlalchemy_history/operation.py"
click node_transaction_py "https://github.com/corridor/sqlalchemy-history/blob/main/sqlalchemy_history/transaction.py"
click node_version_py "https://github.com/corridor/sqlalchemy-history/blob/main/sqlalchemy_history/version.py"
click node_fetcher_py "https://github.com/corridor/sqlalchemy-history/blob/main/sqlalchemy_history/fetcher.py"
click node_expression_reflector_py "https://github.com/corridor/sqlalchemy-history/blob/main/sqlalchemy_history/expression_reflector.py"
click node_reverter_py "https://github.com/corridor/sqlalchemy-history/blob/main/sqlalchemy_history/reverter.py"
click node_utils_py "https://github.com/corridor/sqlalchemy-history/blob/main/sqlalchemy_history/utils.py"
click node_plugins_base_py "https://github.com/corridor/sqlalchemy-history/blob/main/sqlalchemy_history/plugins/base.py"
click node_plugins_activity_py "https://github.com/corridor/sqlalchemy-history/blob/main/sqlalchemy_history/plugins/activity.py"
click node_plugins_null_delete_py "https://github.com/corridor/sqlalchemy-history/blob/main/sqlalchemy_history/plugins/null_delete.py"
click node_plugins_property_mod_tracker_py "https://github.com/corridor/sqlalchemy-history/blob/main/sqlalchemy_history/plugins/property_mod_tracker.py"
click node_plugins_transaction_changes_py "https://github.com/corridor/sqlalchemy-history/blob/main/sqlalchemy_history/plugins/transaction_changes.py"
click node_plugins_transaction_meta_py "https://github.com/corridor/sqlalchemy-history/blob/main/sqlalchemy_history/plugins/transaction_meta.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_sqlalchemy_history___init__ toneBlue
class node_factory_py,node_manager_py,node_unit_of_work_py toneAmber
class node_builder_py,node_schema_py,node_table_builder_py,node_model_builder_py,node_relationship_builder_py toneMint
class node_operation_py,node_transaction_py,node_version_py,node_fetcher_py,node_expression_reflector_py,node_reverter_py,node_utils_py toneRose
class node_plugins_base_py,node_plugins_activity_py,node_plugins_null_delete_py,node_plugins_property_mod_tracker_py,node_plugins_transaction_changes_py,node_plugins_transaction_meta_py toneIndigo
```

## Components

### Public API

Entry points and integration setup for user applications.

- [Package API](https://github.com/corridor/sqlalchemy-history/blob/main/sqlalchemy_history/__init__.py): entrypoint · Public package surface and setup entry point. · `sqlalchemy_history/__init__.py`

### Runtime Core

Event-driven orchestration that bridges SQLAlchemy lifecycle events to history capture.

- [Factory](https://github.com/corridor/sqlalchemy-history/blob/main/sqlalchemy_history/factory.py): bootstrap · Creates and wires versioning infrastructure. · `sqlalchemy_history/factory.py`
- [Manager](https://github.com/corridor/sqlalchemy-history/blob/main/sqlalchemy_history/manager.py): orchestrator · Coordinates mapper/session integration and versioning state. · `sqlalchemy_history/manager.py`
- [Unit of Work](https://github.com/corridor/sqlalchemy-history/blob/main/sqlalchemy_history/unit_of_work.py): session-flow · Tracks flush/commit lifecycle and groups changes into transactions. · `sqlalchemy_history/unit_of_work.py`

### Schema Builders

Builds version tables, mapped history classes, and relationship metadata.

- [Builder](https://github.com/corridor/sqlalchemy-history/blob/main/sqlalchemy_history/builder.py): composition · High-level composition layer for schema and model generation. · `sqlalchemy_history/builder.py`
- [Schema](https://github.com/corridor/sqlalchemy-history/blob/main/sqlalchemy_history/schema.py): schema-api · Defines versioning schema conventions and configuration. · `sqlalchemy_history/schema.py`
- [Table Builder](https://github.com/corridor/sqlalchemy-history/blob/main/sqlalchemy_history/table_builder.py): table-gen · Generates companion version tables for mapped models. · `sqlalchemy_history/table_builder.py`
- [Model Builder](https://github.com/corridor/sqlalchemy-history/blob/main/sqlalchemy_history/model_builder.py): model-gen · Creates mapped history classes for versioned entities. · `sqlalchemy_history/model_builder.py`
- [Rel Builder](https://github.com/corridor/sqlalchemy-history/blob/main/sqlalchemy_history/relationship_builder.py): relationship-gen · Adds version-aware relationship metadata and reconstruction hooks. · `sqlalchemy_history/relationship_builder.py`

### History Flow

Captured audit data, queries, and revert logic.

- [Operation](https://github.com/corridor/sqlalchemy-history/blob/main/sqlalchemy_history/operation.py): change-record · Represents detected ORM mutations and operation types. · `sqlalchemy_history/operation.py`
- [Transaction](https://github.com/corridor/sqlalchemy-history/blob/main/sqlalchemy_history/transaction.py): audit-record · Stores transaction-level audit metadata and grouping. · `sqlalchemy_history/transaction.py`
- [Version](https://github.com/corridor/sqlalchemy-history/blob/main/sqlalchemy_history/version.py): history-record · Represents a single historical row for an entity. · `sqlalchemy_history/version.py`
- [Fetcher](https://github.com/corridor/sqlalchemy-history/blob/main/sqlalchemy_history/fetcher.py): state-reader · Extracts current object state and changed values from ORM instances. · `sqlalchemy_history/fetcher.py`
- [Reflector](https://github.com/corridor/sqlalchemy-history/blob/main/sqlalchemy_history/expression_reflector.py): query-adapter · Maps SQLAlchemy expressions to history-aware equivalents. · `sqlalchemy_history/expression_reflector.py`
- [Reverter](https://github.com/corridor/sqlalchemy-history/blob/main/sqlalchemy_history/reverter.py): restore-engine · Restores prior object and relationship state from history. · `sqlalchemy_history/reverter.py`
- [Utils](https://github.com/corridor/sqlalchemy-history/blob/main/sqlalchemy_history/utils.py): support · Shared helpers used across the versioning pipeline. · `sqlalchemy_history/utils.py`

### Plugins

Composable behaviors that extend the core versioning pipeline.

- [Plugin Base](https://github.com/corridor/sqlalchemy-history/blob/main/sqlalchemy_history/plugins/base.py): extension-contract · Defines the extension interface for plugin behaviors. · `sqlalchemy_history/plugins/base.py`
- [Activity](https://github.com/corridor/sqlalchemy-history/blob/main/sqlalchemy_history/plugins/activity.py): plugin · Adds actor or activity context to transactions. · `sqlalchemy_history/plugins/activity.py`
- [Null Delete](https://github.com/corridor/sqlalchemy-history/blob/main/sqlalchemy_history/plugins/null_delete.py): plugin · Customizes delete handling semantics. · `sqlalchemy_history/plugins/null_delete.py`
- [Mod Tracker](https://github.com/corridor/sqlalchemy-history/blob/main/sqlalchemy_history/plugins/property_mod_tracker.py): plugin · Tracks per-field modification flags. · `sqlalchemy_history/plugins/property_mod_tracker.py`
- [Tx Changes](https://github.com/corridor/sqlalchemy-history/blob/main/sqlalchemy_history/plugins/transaction_changes.py): plugin · Aggregates changes at transaction scope. · `sqlalchemy_history/plugins/transaction_changes.py`
- [Tx Meta](https://github.com/corridor/sqlalchemy-history/blob/main/sqlalchemy_history/plugins/transaction_meta.py): plugin · Attaches extra metadata to transactions. · `sqlalchemy_history/plugins/transaction_meta.py`

## Connections

- Package API → Factory: setup API · User code enters versioning through the package API and setup call.
- Factory → Manager: builds · Factory creates the central manager and wires dependencies.
- Manager → Unit of Work: drives · Manager delegates session lifecycle work to the unit of work.
- Manager → Builder: configures · Manager coordinates schema/model construction for versioned entities.
- Builder → Schema: uses · Builder applies schema conventions and configuration.
- Builder → Table Builder: creates tables · Builder delegates version table generation.
- Builder → Model Builder: creates models · Builder delegates mapped history class generation.
- Builder → Rel Builder: adds relations · Builder delegates relationship metadata handling.
- Table Builder → Version: materializes · Generated tables back the version records.
- Model Builder → Version: maps · Generated history classes represent version rows.
- Rel Builder → Reverter: supports · Relationship metadata is used when restoring object graphs.
- Unit of Work → Fetcher: captures state · Unit of work reads current object state during flush processing.
- Fetcher → Operation: detects · Fetched state is compared to derive operations.
- Operation → Transaction: groups into · Operations are associated with a transaction boundary.
- Transaction → Version: persists · Transaction metadata is linked with version rows.
- Unit of Work → Version: writes · The write path produces version rows from detected changes.
- Reflector → Utils: relies on · Expression handling uses shared helper logic.
- Reflector → Reverter: adapts queries · Reflection helps query temporal state and restore targets.
- Reverter → Version: reads history · Reverter loads prior version rows to reconstruct state.
- Plugin Base → Activity: extends · Concrete plugins implement the shared extension contract.
- Plugin Base → Null Delete: extends · Concrete plugins implement the shared extension contract.
- Plugin Base → Mod Tracker: extends · Concrete plugins implement the shared extension contract.
- Plugin Base → Tx Changes: extends · Concrete plugins implement the shared extension contract.
- Plugin Base → Tx Meta: extends · Concrete plugins implement the shared extension contract.
- Activity → Transaction: annotates · Activity plugin enriches transaction records with context.
- Mod Tracker → Version: flags fields · Modification tracking annotates versioned properties.
- Tx Changes → Transaction: aggregates · Aggregates changes at the transaction layer.
- Tx Meta → Transaction: adds metadata · Attaches extra transaction metadata.
- Null Delete → Operation: changes deletes · Delete semantics alter captured operations.
