# krile136/apexeloquent architecture

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

- Interactive diagram: https://gitdiagram.com/krile136/apexeloquent
- Repository: https://github.com/krile136/apexeloquent

## Overview

##### Project Type & Purpose
- ApexEloquent is an open-source Apex ORM framework for Salesforce, inspired by Laravel Eloquent.
- Its goal is to replace raw SOQL string concatenation with a fluent, typesafe query builder (Scribe), provide an execution layer (Eloquent) that maps results into IEntry objects, and enable database-free unit testing via MockEloquent/MockEntry.

##### File Structure Overview
- Top-level classes:
- Scribe.cls (+ metadata) – the fluent SOQL builder
- Eloquent.cls / IEloquent.cls – execution API for queries
- Entry abstractions (Entries folder) – IEntry, AbstractEntry, Entry, MockEntry
- Clauses modules:
– ConditionClauses (implement IConditionClause – where* methods)
– AggregateClauses (implement IAggregateClause – groupBy, having)
- FieldStructure.cls – holds metadata about SObjects/fields
- tests & mock modules (MockEloquent, MockEntry, unit tests)
- Deployment artifacts:
- manifest/package-empty.xml, manifest/uninstall.xml
- Makefile, GitHub Actions workflow (deploy.yml)

##### Main Architectural Components
A. Query Builder Layer
- Scribe API
- ConditionClauses & AggregateClauses (Strategy pattern)
- FieldStructure (metadata provider)
B. Execution Layer
- Eloquent (implements IEloquent)
- Transforms Scribe → SOQL string → Database.query → List<SObject>
- Maps SObjects → Entry instances (AbstractEntry → Entry)
C. Domain Model
- IEntry interface, AbstractEntry, Entry, MockEntry
- Provides get(), getName(), getParent(), getChildren(), getThrough()
D. Test Double Layer
- MockEloquent (implements IEloquent)
- MockEntry
- Enables in-memory “queries” and parent/child/through relationships without DML
E. External System
- Salesforce database & metadata (SObjects, fields)
- Database.query, DML operations

##### Component Interactions & Data Flow
1. Developer code calls Scribe.source(...) → builds a Scribe instance.
2. Scribe accumulates ConditionClause and AggregateClause objects.
3. Developer passes Scribe to Eloquent.get()/first()/getAggregate().
4. Eloquent invokes Scribe.toSoql(), executes Database.query().
5. Eloquent uses FieldStructure to map raw SObject records into Entry objects.
6. Entry exposes values via IEntry API; relationships fetched by nested Scribe builders.
7. In tests, developer injects MockEloquent; Scribe is bypassed and predetermined MockEntry trees are returned.

##### Key Architectural Patterns & Principles
- Fluent Interface (Scribe) for readable query composition
- Strategy Pattern for clause implementations (IConditionClause, IAggregateClause)
- Dependency Inversion / Interface-based design (IEloquent, IEntry) to allow mocking
- Separation of Concerns: builder vs. executor vs. domain model vs. test double
- Metadata abstraction via FieldStructure

##### Step-by-Step Approach
c. Inside Execution Layer, show FieldStructure feeding metadata to Eloquent and Entry.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Query Builder Layer
    subgraph "Query Builder Layer"
        Scribe["Scribe (Builder)"]:::builder
        ConditionClauses["ConditionClauses (IConditionClause implementations)"]:::builder
        AggregateClauses["AggregateClauses (IAggregateClause implementations)"]:::builder
    end

    %% Execution Layer
    subgraph "Execution Layer"
        IEloquent["IEloquent (Interface)"]:::executor
        Eloquent["Eloquent (Executor)"]:::executor
        FieldStructure["FieldStructure (Metadata Provider)"]:::executor
    end

    %% Domain Model
    subgraph "Domain Model"
        IEntry["IEntry (Interface)"]:::executor
        AbstractEntry["AbstractEntry"]:::executor
        Entry["Entry"]:::executor
    end

    %% Test Double Layer
    subgraph "Test Layer"
        MockEloquent["MockEloquent"]:::test
        MockEntry["MockEntry"]:::test
    end

    %% External System
    SalesforceDB["Salesforce Database"]:::external

    %% Builder interactions
    Scribe -->|"uses clauses"| ConditionClauses
    Scribe -->|"uses clauses"| AggregateClauses

    %% Builder to Execution
    Scribe -->|"passed to"| Eloquent

    %% Execution interactions
    Eloquent -->|"implements"| IEloquent
    Eloquent -->|"uses metadata"| FieldStructure
    Eloquent -->|"executes query"| SalesforceDB
    SalesforceDB -->|"returns SObjects"| Eloquent
    Eloquent -->|"maps to"| Entry

    %% Domain relationships
    Entry -->|extends| AbstractEntry
    AbstractEntry -->|implements| IEntry

    %% Test Double interactions
    MockEloquent -->|"implements"| IEloquent
    MockEloquent -->|"returns"| MockEntry
    MockEntry -->|"implements"| IEntry

    %% Click Events
    click Scribe "https://github.com/krile136/apexeloquent/blob/main/Scribe.cls"
    click ConditionClauses "https://github.com/krile136/apexeloquent/tree/main/ConditionClauses/"
    click AggregateClauses "https://github.com/krile136/apexeloquent/tree/main/AggregateClauses/"
    click FieldStructure "https://github.com/krile136/apexeloquent/blob/main/FieldStructure.cls"
    click IEloquent "https://github.com/krile136/apexeloquent/blob/main/Eloquents/IEloquent.cls"
    click Eloquent "https://github.com/krile136/apexeloquent/blob/main/Eloquents/Eloquent.cls"
    click IEntry "https://github.com/krile136/apexeloquent/blob/main/Entries/IEntry.cls"
    click AbstractEntry "https://github.com/krile136/apexeloquent/blob/main/Entries/AbstractEntry.cls"
    click Entry "https://github.com/krile136/apexeloquent/blob/main/Entries/Entry.cls"
    click MockEloquent "https://github.com/krile136/apexeloquent/blob/main/Eloquents/MockEloquent.cls"
    click MockEntry "https://github.com/krile136/apexeloquent/blob/main/Entries/MockEntry.cls"

    %% Styles
    classDef builder fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef executor fill:#90EE90,stroke:#333,stroke-width:1px
    classDef test fill:#FFA500,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
```
