# luissantiago/elogquent architecture

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

- Interactive diagram: https://gitdiagram.com/luissantiago/elogquent
- Repository: https://github.com/luissantiago/elogquent

## Overview

##### Project Type and Purpose
- This is a Laravel package (“Elogquent”) that plugs into any Laravel application to automatically audit all changes to Eloquent models, store them in a dedicated table, and allow restorations.
- It provides an Observer-based change‐tracking system, queue‐based job processing, a repository for data access, and artisan commands for installation and change restoration.

##### Main Components
a. Host Laravel Application (the “consumer”)
- Bootstraps the package via ElogquentServiceProvider
- Holds user models that “use Elogquent” trait
b. Elogquent Package Core
- Service Provider (registers Observer, Commands, Config)
- Trait (Elogquent) that attaches Observer to model events
- Observer (ElogquentObserver) that listens to model events and dispatches Jobs
- Jobs (ProcessCreateEntry, ProcessRemoveDuplicates, ProcessClearExceededLimit, ProcessRestoreChanges)
- Repository (contract + ElogquentDatabaseRepository) implementing data‐access logic
- Model (ElogquentEntry) representing the audit‐trail table
- Artisan Commands (install, restore)
- Configuration (`config/elogquent.php`)
c. Infrastructure
- Database (change history table, migrations)
- Laravel Queue (driver, connection, queue name)

##### Component Relationships & Data Flows
1. At runtime, any Eloquent model using the Elogquent trait emits “created/updated/deleted” events.
2. ElogquentObserver catches these events and packages them into Jobs.
3. Jobs are dispatched to the Laravel Queue.
4. Queue Worker picks up jobs and invokes the Repository to write/read the ElogquentEntry table.
5. Restore command or restore‐job fetches historical data via the Repository and updates the target model to a previous state.

##### Architectural Patterns & Design Principles
- Observer pattern: separating change‐detection logic from models
- Command pattern: encapsulating install/restore logic as artisan commands
- Repository pattern: abstracting database I/O behind an interface
- Queue‐based asynchronous processing for non‐blocking model operations
- Trait‐based mixin to keep models free of boilerplate
- Configurable via a `config/elogquent.php` file following Laravel conventions

##### Detailed Element Checklist
- Each component must be individually boxed and clearly named
- How the artisan commands hook into the ServiceProvider

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layers
    subgraph "Host Laravel Application"
        direction TB
        App["Laravel Application"]:::framework
        Config["config/elogquent.php"]:::package
        App -->|boots| SP["ElogquentServiceProvider"]:::package
        SP -->|publishes config| Config
        App -->|uses| Models["Eloquent Models"]:::framework
        Models -->|includes| Trait["Elogquent Trait"]:::package
    end

    subgraph "Package Core"
        direction TB
        SP -->|registers| Observer["ElogquentObserver"]:::package
        Trait -->|attaches| Observer
        Observer -->|dispatchJobs| Queue["Laravel Queue\n(driver,connection)"]:::framework
        Queue --> Worker(["Queue Worker"]):::infrastructure
        Worker -->|executes| Jobs
        subgraph "Jobs"
            direction TB
            PC["ProcessCreateEntry"]:::package
            PRD["ProcessRemoveDuplicates"]:::package
            PCE["ProcessClearExceededLimit"]:::package
            PRC["ProcessRestoreChanges"]:::package
        end
        Jobs -->|use| RepositoryImpl["ElogquentDatabaseRepository"]:::package
        Jobs -->|interface| Repository["ElogquentRepositoryInterface"]:::package
        subgraph "Repository"
            direction TB
            Repository --> RepositoryImpl
            RepositoryImpl -->|CRUD| ModelEntry["ElogquentEntry Model"]:::package
        end
    end

    subgraph "Infrastructure"
        direction TB
        DB["Database (elogquent_entries)"]:::framework
        ModelEntry -->|stores| DB
        subgraph "Artisan Commands"
            direction TB
            IC["InstallCommand"]:::package
            RC["RestoreChangeCommand"]:::package
        end
        IC -->|migrates| DB
        RC -->|restoreVia| Repository
    end

    %% Click Events
    click SP "https://github.com/luissantiago/elogquent/blob/main/src/ElogquentServiceProvider.php"
    click Trait "https://github.com/luissantiago/elogquent/blob/main/src/Traits/Elogquent.php"
    click Observer "https://github.com/luissantiago/elogquent/blob/main/src/Observers/ElogquentObserver.php"
    click PC "https://github.com/luissantiago/elogquent/blob/main/src/Jobs/ProcessCreateEntry.php"
    click PRD "https://github.com/luissantiago/elogquent/blob/main/src/Jobs/ProcessRemoveDuplicates.php"
    click PCE "https://github.com/luissantiago/elogquent/blob/main/src/Jobs/ProcessClearExceededLimit.php"
    click PRC "https://github.com/luissantiago/elogquent/blob/main/src/Jobs/ProcessRestoreChanges.php"
    click Repository "https://github.com/luissantiago/elogquent/blob/main/src/Contracts/ElogquentRepositoryInterface.php"
    click RepositoryImpl "https://github.com/luissantiago/elogquent/blob/main/src/Repositories/ElogquentDatabaseRepository.php"
    click ModelEntry "https://github.com/luissantiago/elogquent/blob/main/src/Models/ElogquentEntry.php"
    click IC "https://github.com/luissantiago/elogquent/blob/main/src/Commands/InstallCommand.php"
    click RC "https://github.com/luissantiago/elogquent/blob/main/src/Commands/RestoreChangeCommand.php"
    click Config "https://github.com/luissantiago/elogquent/blob/main/config/elogquent.php"

    %% Styles
    classDef framework fill:#a2d2ff,stroke:#000;
    classDef package fill:#caffbf,stroke:#000;
    classDef infrastructure fill:#ffd6a5,stroke:#000;
```
