# erickpulido/enterprise-transaction-engine architecture

> Architecture diagram of the GitHub repository erickpulido/enterprise-transaction-engine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/erickpulido/enterprise-transaction-engine
- Repository: https://github.com/erickpulido/enterprise-transaction-engine

## Overview

This is a Laravel application skeleton with a concrete transaction-engine subsystem: it hashes instructions for idempotency, locks and validates accounts, updates balances and records ledger entries, then queues a ClickHouse projection after commit. The shown files do not expose a transaction-facing route or controller, so the graph starts at the engine rather than inventing a user-to-result path. The README describes Laravel generally, not additional application capabilities; unsampled schema details and runtime wiring are represented only where the tree or excerpts support them.

Main entry points: [`app/Services/DatabaseTransactionEngine.php`](https://github.com/erickpulido/enterprise-transaction-engine/blob/main/app/Services/DatabaseTransactionEngine.php) (Database Engine), [`app/Jobs/ProjectTransactionToClickHouseJob.php`](https://github.com/erickpulido/enterprise-transaction-engine/blob/main/app/Jobs/ProjectTransactionToClickHouseJob.php) (ClickHouse Projection Job), [`app/Providers/AppServiceProvider.php`](https://github.com/erickpulido/enterprise-transaction-engine/blob/main/app/Providers/AppServiceProvider.php) (Service Binding), [`app/Contracts/TransactionEngineInterface.php`](https://github.com/erickpulido/enterprise-transaction-engine/blob/main/app/Contracts/TransactionEngineInterface.php) (Engine Contract)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Laravel Runtime"]
  node_http["HTTP Runtime<br/>[index.php]"]
  node_bootstrap["App Bootstrap<br/>[app.php]"]
  node_provider["Service Binding"]
end

subgraph group_transaction["Transaction Processing"]
  node_engine_contract["Engine Contract"]
  node_instruction["Transaction Instruction"]
  node_engine["Database Engine"]
  node_exceptions["Transaction Exceptions"]
end

subgraph group_persistence["Persistence"]
  node_account_store[("Account Records")]
  node_idempotency_store[("Idempotency Records")]
  node_ledger_store[("Ledger Entries")]
  node_user_model["User Model<br/>[User.php]"]
end

subgraph group_projection["Analytics Projection"]
  node_projection_job["ClickHouse Projection Job"]
  node_queue["Laravel Queue"]
  node_clickhouse[("ClickHouse")]
end

node_http -->|"loads app"| node_bootstrap
node_provider -->|"binds contract"| node_engine_contract
node_provider -->|"selects implementation"| node_engine
node_engine -->|"accepts instruction"| node_instruction
node_engine -->|"implements contract"| node_engine_contract
node_engine -->|"checks and records"| node_idempotency_store
node_engine -->|"locks and updates"| node_account_store
node_engine -->|"inserts entry"| node_ledger_store
node_engine -->|"throws on invalid"| node_exceptions
node_engine -->|"dispatches after commit"| node_projection_job
node_projection_job -->|"runs asynchronously"| node_queue
node_projection_job -->|"posts event"| node_clickhouse

click node_http "https://github.com/erickpulido/enterprise-transaction-engine/blob/main/public/index.php"
click node_bootstrap "https://github.com/erickpulido/enterprise-transaction-engine/blob/main/bootstrap/app.php"
click node_provider "https://github.com/erickpulido/enterprise-transaction-engine/blob/main/app/Providers/AppServiceProvider.php"
click node_engine_contract "https://github.com/erickpulido/enterprise-transaction-engine/blob/main/app/Contracts/TransactionEngineInterface.php"
click node_instruction "https://github.com/erickpulido/enterprise-transaction-engine/blob/main/app/DTO/TransactionInstructionDTO.php"
click node_engine "https://github.com/erickpulido/enterprise-transaction-engine/blob/main/app/Services/DatabaseTransactionEngine.php"
click node_exceptions "https://github.com/erickpulido/enterprise-transaction-engine/tree/main/app/Exceptions"
click node_account_store "https://github.com/erickpulido/enterprise-transaction-engine/blob/main/database/migrations/2026_10_01_230102_create_accounts_table.php"
click node_idempotency_store "https://github.com/erickpulido/enterprise-transaction-engine/blob/main/database/migrations/2026_10_01_225840_create_idempotency_keys_table.php"
click node_ledger_store "https://github.com/erickpulido/enterprise-transaction-engine/blob/main/database/migrations/2026_10_01_230250_create_ledger_entries_table.php"
click node_user_model "https://github.com/erickpulido/enterprise-transaction-engine/blob/main/app/Models/User.php"
click node_projection_job "https://github.com/erickpulido/enterprise-transaction-engine/blob/main/app/Jobs/ProjectTransactionToClickHouseJob.php"

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_http,node_bootstrap,node_provider toneBlue
class node_engine_contract,node_instruction,node_engine,node_exceptions toneAmber
class node_account_store,node_idempotency_store,node_ledger_store,node_user_model toneMint
class node_projection_job,node_queue,node_clickhouse toneRose
```

## Components

### Laravel Runtime

- [HTTP Runtime](https://github.com/erickpulido/enterprise-transaction-engine/blob/main/public/index.php): `public/index.php`
- [App Bootstrap](https://github.com/erickpulido/enterprise-transaction-engine/blob/main/bootstrap/app.php): `bootstrap/app.php`
- [Service Binding](https://github.com/erickpulido/enterprise-transaction-engine/blob/main/app/Providers/AppServiceProvider.php): `app/Providers/AppServiceProvider.php`

### Transaction Processing

- [Engine Contract](https://github.com/erickpulido/enterprise-transaction-engine/blob/main/app/Contracts/TransactionEngineInterface.php): `app/Contracts/TransactionEngineInterface.php`
- [Transaction Instruction](https://github.com/erickpulido/enterprise-transaction-engine/blob/main/app/DTO/TransactionInstructionDTO.php): `app/DTO/TransactionInstructionDTO.php`
- [Database Engine](https://github.com/erickpulido/enterprise-transaction-engine/blob/main/app/Services/DatabaseTransactionEngine.php): `app/Services/DatabaseTransactionEngine.php`
- [Transaction Exceptions](https://github.com/erickpulido/enterprise-transaction-engine/tree/main/app/Exceptions): `app/Exceptions`

### Persistence

- [Account Records](https://github.com/erickpulido/enterprise-transaction-engine/blob/main/database/migrations/2026_10_01_230102_create_accounts_table.php): `database/migrations/2026_10_01_230102_create_accounts_table.php`
- [Idempotency Records](https://github.com/erickpulido/enterprise-transaction-engine/blob/main/database/migrations/2026_10_01_225840_create_idempotency_keys_table.php): `database/migrations/2026_10_01_225840_create_idempotency_keys_table.php`
- [Ledger Entries](https://github.com/erickpulido/enterprise-transaction-engine/blob/main/database/migrations/2026_10_01_230250_create_ledger_entries_table.php): `database/migrations/2026_10_01_230250_create_ledger_entries_table.php`
- [User Model](https://github.com/erickpulido/enterprise-transaction-engine/blob/main/app/Models/User.php): `app/Models/User.php`

### Analytics Projection

- [ClickHouse Projection Job](https://github.com/erickpulido/enterprise-transaction-engine/blob/main/app/Jobs/ProjectTransactionToClickHouseJob.php): `app/Jobs/ProjectTransactionToClickHouseJob.php`
- **Laravel Queue**
- **ClickHouse**

## Connections

- HTTP Runtime → App Bootstrap: loads app (evidence: `public/index.php`)
- Service Binding → Engine Contract: binds contract (evidence: `app/Providers/AppServiceProvider.php`)
- Service Binding → Database Engine: selects implementation (evidence: `app/Providers/AppServiceProvider.php`)
- Database Engine → Transaction Instruction: accepts instruction (evidence: `app/Services/DatabaseTransactionEngine.php`)
- Database Engine → Engine Contract: implements contract (evidence: `app/Services/DatabaseTransactionEngine.php`)
- Database Engine → Idempotency Records: checks and records (evidence: `app/Services/DatabaseTransactionEngine.php`)
- Database Engine → Account Records: locks and updates (evidence: `app/Services/DatabaseTransactionEngine.php`)
- Database Engine → Ledger Entries: inserts entry (evidence: `app/Services/DatabaseTransactionEngine.php`)
- Database Engine → Transaction Exceptions: throws on invalid (evidence: `app/Services/DatabaseTransactionEngine.php`)
- Database Engine → ClickHouse Projection Job: dispatches after commit (evidence: `app/Services/DatabaseTransactionEngine.php`)
- ClickHouse Projection Job → Laravel Queue: runs asynchronously (evidence: `app/Jobs/ProjectTransactionToClickHouseJob.php`)
- ClickHouse Projection Job → ClickHouse: posts event (evidence: `app/Jobs/ProjectTransactionToClickHouseJob.php`)
