# clarityx-dev-team/eloquentsalesforce architecture

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

- Interactive diagram: https://gitdiagram.com/clarityx-dev-team/eloquentsalesforce
- Repository: https://github.com/clarityx-dev-team/eloquentsalesforce

## Overview

##### Project Type and Purpose
- This is an open-source Laravel package (rob-lester-jr04/eloquent-sales-force) that provides an Eloquent-style ORM layer on top of the Salesforce REST API.
- It lets Laravel developers treat Salesforce objects like native Eloquent models, using familiar builders, relationships, observers, and console commands.

##### File Structure Analysis
- Top-level files: composer.json (package definition), .env_example, config/eloquent_sf.php (package config), docs/ (static site docs), routes/api.php (optional demo or integration routes).
- src/ contains the package source, organized by:
· Console/ (Artisan commands: MakeModelCommand, SyncFromSalesforce)
· Database/ (SOQLConnection, SOQLBuilder, Grammar, Relationship classes)
· Facades/ (SObjects facade)
· Fakers/ (for testing)
· Exceptions/ (API and query errors)
· Observers/ (Synchronizer)
· Traits/ (SyncsWithSalesforce)
· ServiceProvider.php (registers core services, facade, database connection)
· Model.php, SalesForceObject.php (base model classes)
- tests/ covers unit tests, including fake connections.

##### README Insights
- Confirms the package’s intent and provides links to full docs.

a. Main Components
1. Laravel Application
2. EloquentSalesForce Package
- ServiceProvider
- Facade (SObjects)
- Base Models (Model.php, SalesForceObject.php)
- Database Layer (SOQLConnection, SOQLBuilder, SOQLGrammar, Relationship classes)
- Traits & Observers (SyncsWithSalesforce, Synchronizer)
- Console Commands
3. HTTP Client (e.g., Guzzle)
4. Salesforce REST API
5. (Optional) Local Storage for caching or in-memory (memory folder)
b. Relationships & Data Flow
- The Laravel App boots → ServiceProvider registers the connection (under “salesforce”), the Facade alias, and binds commands.
- When user code calls SObjects::query() or Model::all(), the Facade routes calls into the package’s Builder → Grammar → Connection → HTTP Client → Salesforce API.
- Responses return JSON → parsed by SOQLConnection → hydrated into Model instances.
- Observers/Traits hook into Model events (saving, deleting) to sync changes back to Salesforce.
- Console commands scaffold models or bulk-sync data using the same connection pipeline.
c. Architectural Patterns & Principles
- Service Provider pattern (registers services).
- Facade pattern (static interface to complex subsystem).
- Active Record/ORM pattern (Model).
- Command pattern (Artisan commands).
- Observer pattern (Synchronizer).
- Separation of concerns: Database layer isolated from HTTP client.
d. Key Technologies & Libraries
- PHP 7+, Composer autoloading.
- Laravel’s service container and facades.
- Guzzle (or built-in HTTP client).
- PHPUnit for testing with fakers and memory drivers.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Framework Layer
    subgraph "Laravel Application" 
        direction TB
        LaravelApp["Laravel App"]:::framework
        Config["Config (eloquent_sf.php)"]:::framework
        Routes["Demo Routes (api.php)"]:::framework
    end

    %% Package Layer
    subgraph "EloquentSalesForce Package" 
        direction TB

        ServiceProvider["ServiceProvider"]:::package
        Facade["SObjects Facade"]:::facade

        subgraph "Base Models" 
            direction TB
            Model["Model.php"]:::model
            SalesForceObject["SalesForceObject.php"]:::model
        end

        subgraph "Database Layer" 
            direction TB
            SOQLBuilder["SOQLBuilder"]:::db
            SOQLGrammar["SOQLGrammar"]:::db
            SOQLConnection["SOQLConnection"]:::db
            SOQLBatch["SOQLBatch"]:::db
            SOQLHasOne["SOQLHasOne"]:::db
            SOQLHasMany["SOQLHasMany"]:::db
            SOQLHasOneOrMany["SOQLHasOneOrMany"]:::db
        end

        subgraph "Traits & Observers" 
            direction TB
            SyncsWithSalesforce["SyncsWithSalesforce Trait"]:::package
            Synchronizer["Synchronizer Observer"]:::package
        end

        subgraph "Console Commands" 
            direction TB
            MakeModelCommand["MakeModelCommand"]:::console
            SyncFromSalesforce["SyncFromSalesforce"]:::console
            Stub["model.stub"]:::console
        end
    end

    %% External Systems
    HTTPClient["HTTP Client (Guzzle)"]:::external
    SalesforceAPI["Salesforce REST API"]:::external
    Fakers["SObjectsFake (Fakers)"]:::external
    Tests["Tests Suite"]:::external
    TestModels["Demo/Test Models & Observer"]:::external

    %% Connections
    LaravelApp -->|"reads"| Config
    LaravelApp -->|"calls"| Routes
    LaravelApp -->|"boots"| ServiceProvider
    ServiceProvider -->|"registers facade"| Facade
    ServiceProvider -->|"binds connection"| SOQLConnection
    ServiceProvider -->|"publishes config"| Config
    ServiceProvider -->|"registers commands"| MakeModelCommand
    ServiceProvider -->|"registers commands"| SyncFromSalesforce

    Facade -->|"static calls"| SOQLBuilder
    SOQLBuilder -->|"uses grammar"| SOQLGrammar
    SOQLBuilder -->|"builds queries"| SOQLBatch
    SOQLBatch -->|"executes on"| SOQLConnection
    SOQLConnection -->|"sends HTTP"| HTTPClient
    HTTPClient -->|"requests"| SalesforceAPI
    SalesforceAPI -->|"responses JSON"| SOQLConnection
    SOQLConnection -->|"hydrates"| Model
    SOQLConnection -->|"hydrates"| SalesForceObject

    Model -->|"uses trait"| SyncsWithSalesforce
    SalesForceObject -->|"observed by"| Synchronizer

    MakeModelCommand -->|"scaffolds"| Model
    SyncFromSalesforce -->|"bulk sync via"| SOQLConnection

    Routes -->|"example calls"| Facade
    SyncsWithSalesforce -->|"sync logic"| SOQLConnection

    Fakers -->|"provides fake"| SOQLConnection
    Tests -->|"test cases"| Fakers

    TestModels -->|"demo"| Synchronizer

    %% Click Events
    click ServiceProvider "https://github.com/clarityx-dev-team/eloquentsalesforce/blob/master/src/ServiceProvider.php"
    click Facade "https://github.com/clarityx-dev-team/eloquentsalesforce/blob/master/src/Facades/SObjects.php"
    click Model "https://github.com/clarityx-dev-team/eloquentsalesforce/blob/master/src/Model.php"
    click SalesForceObject "https://github.com/clarityx-dev-team/eloquentsalesforce/blob/master/src/SalesForceObject.php"
    click SOQLConnection "https://github.com/clarityx-dev-team/eloquentsalesforce/blob/master/src/Database/SOQLConnection.php"
    click SOQLBuilder "https://github.com/clarityx-dev-team/eloquentsalesforce/blob/master/src/Database/SOQLBuilder.php"
    click SOQLGrammar "https://github.com/clarityx-dev-team/eloquentsalesforce/blob/master/src/Database/SOQLGrammar.php"
    click SOQLBatch "https://github.com/clarityx-dev-team/eloquentsalesforce/blob/master/src/Database/SOQLBatch.php"
    click SOQLHasOne "https://github.com/clarityx-dev-team/eloquentsalesforce/blob/master/src/Database/SOQLHasOne.php"
    click SOQLHasMany "https://github.com/clarityx-dev-team/eloquentsalesforce/blob/master/src/Database/SOQLHasMany.php"
    click SOQLHasOneOrMany "https://github.com/clarityx-dev-team/eloquentsalesforce/blob/master/src/Database/SOQLHasOneOrMany.php"
    click SyncsWithSalesforce "https://github.com/clarityx-dev-team/eloquentsalesforce/blob/master/src/Traits/SyncsWithSalesforce.php"
    click Synchronizer "https://github.com/clarityx-dev-team/eloquentsalesforce/blob/master/src/Observers/Syncronizer.php"
    click MakeModelCommand "https://github.com/clarityx-dev-team/eloquentsalesforce/blob/master/src/Console/MakeModelCommand.php"
    click SyncFromSalesforce "https://github.com/clarityx-dev-team/eloquentsalesforce/blob/master/src/Console/SyncFromSalesforce.php"
    click Stub "https://github.com/clarityx-dev-team/eloquentsalesforce/blob/master/src/Console/stubs/model.stub"
    click Config "https://github.com/clarityx-dev-team/eloquentsalesforce/blob/master/config/eloquent_sf.php"
    click Routes "https://github.com/clarityx-dev-team/eloquentsalesforce/blob/master/routes/api.php"
    click Fakers "https://github.com/clarityx-dev-team/eloquentsalesforce/blob/master/src/Fakers/SObjectsFake.php"
    click Tests "https://github.com/clarityx-dev-team/eloquentsalesforce/blob/master/tests/TestCase.php"
    click Tests "https://github.com/clarityx-dev-team/eloquentsalesforce/blob/master/tests/EloquentSalesForceTest.php"
    click TestModels "https://github.com/clarityx-dev-team/eloquentsalesforce/blob/master/src/TestModel.php"
    click TestModels "https://github.com/clarityx-dev-team/eloquentsalesforce/blob/master/src/TestLead.php"
    click TestModels "https://github.com/clarityx-dev-team/eloquentsalesforce/blob/master/src/TestUser.php"
    click TestModels "https://github.com/clarityx-dev-team/eloquentsalesforce/blob/master/src/TestTask.php"
    click TestModels "https://github.com/clarityx-dev-team/eloquentsalesforce/blob/master/src/TestObserver.php"

    %% Styles
    classDef framework fill:#f9f,stroke:#333,stroke-width:2px
    classDef package fill:#bbf,stroke:#333,stroke-width:2px
    classDef facade fill:#fbf,stroke:#333,stroke-width:2px
    classDef model fill:#bfb,stroke:#333,stroke-width:2px
    classDef db fill:#ffb,stroke:#333,stroke-width:2px
    classDef console fill:#fbb,stroke:#333,stroke-width:2px
    classDef external fill:#fff,stroke:#333,stroke-width:2px,stroke-dasharray: 5 5
```
