# ylikscherbak/elasticsearch-audit-bundle architecture

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

- Interactive diagram: https://gitdiagram.com/ylikscherbak/elasticsearch-audit-bundle
- Repository: https://github.com/ylikscherbak/elasticsearch-audit-bundle

## Overview

Elasticsearch Audit Bundle is a Symfony audit-history bundle: it captures Doctrine changes and explicitly submitted domain events, completes and optionally coalesces records, redacts them, then writes synchronously or through Messenger to Elasticsearch. Its read API builds filtered, paginated queries over that history; operational commands check and manage indices. The README documents the main record lifecycle and the Doctrine/Messenger options. Several internals are represented at subsystem level because their source was not excerpted.

Main entry points: [`src/Writer/AuditWriter.php`](https://github.com/ylikscherbak/elasticsearch-audit-bundle/blob/main/src/Writer/AuditWriter.php) (Manual audit calls), [`src/Transport`](https://github.com/ylikscherbak/elasticsearch-audit-bundle/tree/main/src/Transport) (Transport selection), [`src/Transport/Messenger`](https://github.com/ylikscherbak/elasticsearch-audit-bundle/tree/main/src/Transport/Messenger) (Messenger workers), [`src/Elasticsearch/GatewayInterface.php`](https://github.com/ylikscherbak/elasticsearch-audit-bundle/blob/main/src/Elasticsearch/GatewayInterface.php) (Elasticsearch gateway)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Record capture"]
  node_doctrine["Doctrine auditing"]
  node_manual["Manual audit calls<br/>[AuditWriter.php]"]
end

subgraph group_processing["Record processing"]
  node_record["Audit record<br/>[AuditRecord.php]"]
  node_actor["Actor resolution"]
  node_enrich["Record enrichment"]
  node_frames["Coalescing frames<br/>[FrameBuffer.php]"]
  node_redaction["Privacy redaction<br/>[ChangeRedactor.php]"]
  node_created_event["Created event"]
end

subgraph group_delivery["Storage and delivery"]
  node_transport["Transport selection"]
  node_messenger["Messenger workers"]
  node_outbox[("Transactional outbox")]
  node_gateway["Elasticsearch gateway"]
  node_elasticsearch[("Elasticsearch")]
end

subgraph group_reading["History access"]
  node_reader_api["Audit reader<br/>[AuditReader.php]"]
  node_query["Query construction<br/>[QueryBuilder.php]"]
  node_query_model["Filterable query<br/>[AuditQuery.php]"]
end

subgraph group_operations["Configuration and operations"]
  node_commands["Index commands"]
  node_configuration["Bundle configuration"]
end

node_application(("Application"))
node_messenger_bus["Symfony Messenger"]

node_application -->|"records events"| node_manual
node_doctrine -->|"submits changes"| node_manual
node_manual -->|"builds records"| node_record
node_manual -->|"resolves actor"| node_actor
node_manual -->|"runs enrichers"| node_enrich
node_manual -->|"buffers records"| node_frames
node_frames -->|"merges changes"| node_record
node_manual -->|"redacts records"| node_redaction
node_manual -->|"dispatches event"| node_created_event
node_manual -->|"releases records"| node_transport
node_transport -->|"writes directly"| node_gateway
node_transport -->|"queues records"| node_messenger
node_messenger_bus -->|"invokes handlers"| node_messenger
node_messenger -->|"writes batches"| node_gateway
node_gateway -->|"stores and searches"| node_elasticsearch
node_transport -.->|"may use outbox"| node_outbox
node_application -->|"requests history"| node_reader_api
node_reader_api -.->|"builds searches"| node_query
node_reader_api -.->|"searches history"| node_gateway
node_query -->|"reads filters"| node_query_model
node_application -->|"runs index checks"| node_commands
node_configuration -->|"configures services"| node_manual
node_configuration -->|"configures handlers"| node_messenger
node_configuration -->|"enables auditing"| node_doctrine

click node_doctrine "https://github.com/ylikscherbak/elasticsearch-audit-bundle/tree/main/src/Doctrine"
click node_manual "https://github.com/ylikscherbak/elasticsearch-audit-bundle/blob/main/src/Writer/AuditWriter.php"
click node_record "https://github.com/ylikscherbak/elasticsearch-audit-bundle/blob/main/src/Model/AuditRecord.php"
click node_actor "https://github.com/ylikscherbak/elasticsearch-audit-bundle/tree/main/src/Actor"
click node_enrich "https://github.com/ylikscherbak/elasticsearch-audit-bundle/tree/main/src/Contract"
click node_frames "https://github.com/ylikscherbak/elasticsearch-audit-bundle/blob/main/src/Coalescing/FrameBuffer.php"
click node_redaction "https://github.com/ylikscherbak/elasticsearch-audit-bundle/blob/main/src/Privacy/ChangeRedactor.php"
click node_created_event "https://github.com/ylikscherbak/elasticsearch-audit-bundle/blob/main/src/Event/RecordCreatedEvent.php"
click node_transport "https://github.com/ylikscherbak/elasticsearch-audit-bundle/tree/main/src/Transport"
click node_messenger "https://github.com/ylikscherbak/elasticsearch-audit-bundle/tree/main/src/Transport/Messenger"
click node_outbox "https://github.com/ylikscherbak/elasticsearch-audit-bundle/tree/main/src/Transport/Outbox"
click node_gateway "https://github.com/ylikscherbak/elasticsearch-audit-bundle/blob/main/src/Elasticsearch/GatewayInterface.php"
click node_reader_api "https://github.com/ylikscherbak/elasticsearch-audit-bundle/blob/main/src/Reader/AuditReader.php"
click node_query "https://github.com/ylikscherbak/elasticsearch-audit-bundle/blob/main/src/Reader/QueryBuilder.php"
click node_query_model "https://github.com/ylikscherbak/elasticsearch-audit-bundle/blob/main/src/Model/AuditQuery.php"
click node_commands "https://github.com/ylikscherbak/elasticsearch-audit-bundle/tree/main/src/Command"
click node_configuration "https://github.com/ylikscherbak/elasticsearch-audit-bundle/blob/main/src/DependencyInjection/ElasticsearchAuditExtension.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_doctrine,node_manual toneBlue
class node_record,node_actor,node_enrich,node_frames,node_redaction,node_created_event toneAmber
class node_transport,node_messenger,node_outbox,node_gateway,node_elasticsearch toneMint
class node_reader_api,node_query,node_query_model toneRose
class node_commands,node_configuration,node_application,node_messenger_bus toneIndigo
```

## Components

### Record capture

- [Doctrine auditing](https://github.com/ylikscherbak/elasticsearch-audit-bundle/tree/main/src/Doctrine): `src/Doctrine`
- [Manual audit calls](https://github.com/ylikscherbak/elasticsearch-audit-bundle/blob/main/src/Writer/AuditWriter.php): `src/Writer/AuditWriter.php`

### Record processing

- [Audit record](https://github.com/ylikscherbak/elasticsearch-audit-bundle/blob/main/src/Model/AuditRecord.php): `src/Model/AuditRecord.php`
- [Actor resolution](https://github.com/ylikscherbak/elasticsearch-audit-bundle/tree/main/src/Actor): `src/Actor`
- [Record enrichment](https://github.com/ylikscherbak/elasticsearch-audit-bundle/tree/main/src/Contract): `src/Contract`
- [Coalescing frames](https://github.com/ylikscherbak/elasticsearch-audit-bundle/blob/main/src/Coalescing/FrameBuffer.php): `src/Coalescing/FrameBuffer.php`
- [Privacy redaction](https://github.com/ylikscherbak/elasticsearch-audit-bundle/blob/main/src/Privacy/ChangeRedactor.php): `src/Privacy/ChangeRedactor.php`
- [Created event](https://github.com/ylikscherbak/elasticsearch-audit-bundle/blob/main/src/Event/RecordCreatedEvent.php): `src/Event/RecordCreatedEvent.php`

### Storage and delivery

- [Transport selection](https://github.com/ylikscherbak/elasticsearch-audit-bundle/tree/main/src/Transport): `src/Transport`
- [Messenger workers](https://github.com/ylikscherbak/elasticsearch-audit-bundle/tree/main/src/Transport/Messenger): `src/Transport/Messenger`
- [Transactional outbox](https://github.com/ylikscherbak/elasticsearch-audit-bundle/tree/main/src/Transport/Outbox): `src/Transport/Outbox`
- [Elasticsearch gateway](https://github.com/ylikscherbak/elasticsearch-audit-bundle/blob/main/src/Elasticsearch/GatewayInterface.php): `src/Elasticsearch/GatewayInterface.php`
- **Elasticsearch**

### History access

- [Audit reader](https://github.com/ylikscherbak/elasticsearch-audit-bundle/blob/main/src/Reader/AuditReader.php): `src/Reader/AuditReader.php`
- [Query construction](https://github.com/ylikscherbak/elasticsearch-audit-bundle/blob/main/src/Reader/QueryBuilder.php): `src/Reader/QueryBuilder.php`
- [Filterable query](https://github.com/ylikscherbak/elasticsearch-audit-bundle/blob/main/src/Model/AuditQuery.php): `src/Model/AuditQuery.php`

### Configuration and operations

- [Index commands](https://github.com/ylikscherbak/elasticsearch-audit-bundle/tree/main/src/Command): `src/Command`
- [Bundle configuration](https://github.com/ylikscherbak/elasticsearch-audit-bundle/blob/main/src/DependencyInjection/ElasticsearchAuditExtension.php): `src/DependencyInjection/ElasticsearchAuditExtension.php`

### Other components

- **Application**
- **Symfony Messenger**

## Connections

- Application → Manual audit calls: records events
- Doctrine auditing → Manual audit calls: submits changes
- Manual audit calls → Audit record: builds records (evidence: `src/Writer/AuditWriter.php`)
- Manual audit calls → Actor resolution: resolves actor (evidence: `src/Writer/AuditWriter.php`)
- Manual audit calls → Record enrichment: runs enrichers (evidence: `src/Writer/AuditWriter.php`)
- Manual audit calls → Coalescing frames: buffers records (evidence: `src/Writer/AuditWriter.php`)
- Coalescing frames → Audit record: merges changes (evidence: `src/Coalescing/FrameBuffer.php`)
- Manual audit calls → Privacy redaction: redacts records (evidence: `src/Writer/AuditWriter.php`)
- Manual audit calls → Created event: dispatches event (evidence: `src/Writer/AuditWriter.php`)
- Manual audit calls → Transport selection: releases records (evidence: `src/Writer/AuditWriter.php`)
- Transport selection → Elasticsearch gateway: writes directly (evidence: `src/Transport/Messenger/IndexAuditRecordsHandler.php`)
- Transport selection → Messenger workers: queues records (evidence: `src/Transport/Messenger/IndexAuditRecordsHandler.php`)
- Symfony Messenger → Messenger workers: invokes handlers (evidence: `src/Transport/Messenger/IndexAuditRecordsHandler.php`)
- Messenger workers → Elasticsearch gateway: writes batches (evidence: `src/Transport/Messenger/IndexAuditRecordsHandler.php`)
- Elasticsearch gateway → Elasticsearch: stores and searches
- Transport selection → Transactional outbox: may use outbox
- Application → Audit reader: requests history
- Audit reader → Query construction: builds searches
- Audit reader → Elasticsearch gateway: searches history
- Query construction → Filterable query: reads filters (evidence: `src/Reader/QueryBuilder.php`)
- Application → Index commands: runs index checks
- Bundle configuration → Manual audit calls: configures services (evidence: `src/DependencyInjection/ElasticsearchAuditExtension.php`)
- Bundle configuration → Messenger workers: configures handlers (evidence: `src/DependencyInjection/ElasticsearchAuditExtension.php`)
- Bundle configuration → Doctrine auditing: enables auditing (evidence: `src/DependencyInjection/ElasticsearchAuditExtension.php`)
