# neo4j-php/neo4j-php-client architecture

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

- Interactive diagram: https://gitdiagram.com/neo4j-php/neo4j-php-client
- Repository: https://github.com/neo4j-php/neo4j-php-client

## Overview

##### Main Components
- Client Builder & Client: These are the high-level entry points that accept configuration (e.g., authentication, URL, driver selection) and route queries to the appropriate drivers.
- Driver Space: This includes individual drivers for different protocols (Bolt, HTTP and neo4j routing). Represent this as separate nodes or sub-components.
- Authentication Mechanisms: Components under src/Authentication (BasicAuth, KerberosAuth, OpenIDConnectAuth, NoAuth) that are plugged into the client and driver configurations.
- Connection and Session Management: This encompasses connection factories (in src/Bolt and src/Basic), connection pooling (src/Common/ConnectionPoolInterface and its implementations) and session/transaction handling.
- Transaction and Query Execution: Include components for auto-committed queries, transaction functions, and unmanaged transactions. These are orchestrated by sessions that use transaction objects.
- Data Objects and Formatters: The data bags (src/Databags) and formatters (src/Formatter) that encapsulate cypher statements, results, and metadata.
- Utility Components: The common classes and helpers (e.g., ParameterHelper, DNSAddressResolver) that support configuration and runtime decisions.

##### Out the Interactions and Relationships
- The Client routes queries to the appropriate Driver (depending on the alias such as “bolt”, “https” or “neo4j”), so link the Client to multiple “Driver” nodes.
- Within each Driver, indicate that it manages a connection pool and creates Sessions. Show the flow from Driver → Session → Transaction → Query Execution.
- Utility and Helper classes as support nodes connected to both the Client and lower-level drivers.
- Finally, illustrate how Results are processed: the Transaction returns a Result that is managed by Formatters, which then maps Cypher values to PHP types (linking to the Types components).

##### Important Architectural Patterns and Design Principles
- Layered Architecture: Emphasize the separation of configuration (client/driver builder), connection management (driver, session, transaction), query formatting/execution and utility functions.
- Plug-in and Abstraction: Note how distinct authentication implementations and protocol-specific drivers (Bolt vs HTTP) are abstracted behind common contracts (e.g., in src/Contracts).
- Dependency Injection: Show that configuration objects (DriverConfiguration, SessionConfiguration, TransactionConfiguration) are passed through the client-building process.
- Testability: Mention that the clear separation into modules is supported by a comprehensive set of unit/integration tests.

##### Relevant Technologies
- PHP (language and runtime).
- Composer (dependency management as demonstrated by the composer.json).
- Docker (Dockerfile and docker-compose files exist for containerization and testing environments).
- Psalm (static analysis as indicated by psalm.xml) and PHP-CS-Fixer, Rector for code quality.

##### Detail and Clarity
- Do not over-simplify: each abstraction (client, driver, session, transaction) should be clearly represented.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        CB["Client Builder"]:::client
        C["Client"]:::client
        CB -->|"builds"| C
    end

    %% Authentication Mechanisms
    subgraph "Authentication"
        BA["Basic Authentication"]:::auth
        KA["Kerberos Authentication"]:::auth
        OIDC["OpenID Connect"]:::auth
        NA["No Authentication"]:::auth
    end

    %% Driver Layer
    subgraph "Driver Space"
        BD["Bolt Driver"]:::driver
        HD["HTTP/Basic Driver"]:::driver
        ND["Neo4j Routing Driver"]:::driver
        C -->|"selects"| BD
        C -->|"selects"| HD
        C -->|"selects"| ND
        %% Authentication injected into drivers
        BA ---|"injects"| BD
        KA ---|"injects"| BD
        OIDC ---|"injects"| BD
        NA ---|"injects"| BD

        BA ---|"injects"| HD
        KA ---|"injects"| HD
        OIDC ---|"injects"| HD
        NA ---|"injects"| HD

        BA ---|"injects"| ND
        KA ---|"injects"| ND
        OIDC ---|"injects"| ND
        NA ---|"injects"| ND
    end

    %% Connection & Session Management
    subgraph "Connection & Session"
        SCF["Bolt Socket Connection Factory"]:::conn
        STCF["Bolt Stream Connection Factory"]:::conn
        SWCF["Bolt SystemWide Connection Factory"]:::conn
        BCP["Bolt Connection Pool"]:::conn
        BS["Bolt Session"]:::conn
        BCP --> BS
        BD --> BCP
        
        BasicS["Basic Session"]:::conn
        HD --> BasicS

        DNS["DNS Address Resolver"]:::util
        DNS --- BS
        DNS --- BasicS
    end

    %% Transaction and Query Execution
    subgraph "Transaction & Query Execution"
        BUT["Bolt Unmanaged Transaction"]:::trans
        BUTI["Transaction Interface"]:::trans
        BUNI["Basic Unmanaged Transaction"]:::trans
        UTI["Unmanaged Transaction Interface"]:::trans
        
        BS -->|"starts"| BUT
        BUT --> BUTI
        BasicS -->|"starts"| BUNI
        BUNI --> UTI
    end

    %% Data Objects and Result Formatting
    subgraph "Result Processing"
        DB["Data Bags"]:::fmt
        SRF["Summarized Result Formatter"]:::fmt
        BOT["Bolt OGM Translator"]:::fmt
        BUTI --> SRF
        UTI --> SRF
        SRF --> DB
    end

    %% Utility Components
    subgraph "Utility Components"
        CU["Common Utilities"]:::util
        PH["Parameter Helper"]:::util
        T["Types"]:::util
        CU --- C
        CU --- BD
        CU --- HD
        CU --- ND
        PH --- C
        T --- C
    end

    %% Click Events
    click CB "https://github.com/neo4j-php/neo4j-php-client/blob/main/src/ClientBuilder.php"
    click C "https://github.com/neo4j-php/neo4j-php-client/blob/main/src/Client.php"
    
    click BD "https://github.com/neo4j-php/neo4j-php-client/blob/main/src/Bolt/BoltDriver.php"
    click HD "https://github.com/neo4j-php/neo4j-php-client/blob/main/src/Basic/Driver.php"
    click ND "https://github.com/neo4j-php/neo4j-php-client/blob/main/src/Neo4j/Neo4jDriver.php"
    
    click BA "https://github.com/neo4j-php/neo4j-php-client/blob/main/src/Authentication/BasicAuth.php"
    click KA "https://github.com/neo4j-php/neo4j-php-client/blob/main/src/Authentication/KerberosAuth.php"
    click OIDC "https://github.com/neo4j-php/neo4j-php-client/blob/main/src/Authentication/OpenIDConnectAuth.php"
    click NA "https://github.com/neo4j-php/neo4j-php-client/blob/main/src/Authentication/NoAuth.php"
    
    click SCF "https://github.com/neo4j-php/neo4j-php-client/blob/main/src/Bolt/SocketConnectionFactory.php"
    click STCF "https://github.com/neo4j-php/neo4j-php-client/blob/main/src/Bolt/StreamConnectionFactory.php"
    click SWCF "https://github.com/neo4j-php/neo4j-php-client/blob/main/src/Bolt/SystemWideConnectionFactory.php"
    click BCP "https://github.com/neo4j-php/neo4j-php-client/blob/main/src/Bolt/ConnectionPool.php"
    click BS "https://github.com/neo4j-php/neo4j-php-client/blob/main/src/Bolt/Session.php"
    click BasicS "https://github.com/neo4j-php/neo4j-php-client/blob/main/src/Basic/Session.php"
    click DNS "https://github.com/neo4j-php/neo4j-php-client/blob/main/src/Common/DNSAddressResolver.php"
    
    click BUT "https://github.com/neo4j-php/neo4j-php-client/blob/main/src/Bolt/BoltUnmanagedTransaction.php"
    click BUNI "https://github.com/neo4j-php/neo4j-php-client/blob/main/src/Basic/UnmanagedTransaction.php"
    click BUTI "https://github.com/neo4j-php/neo4j-php-client/blob/main/src/Contracts/TransactionInterface.php"
    click UTI "https://github.com/neo4j-php/neo4j-php-client/blob/main/src/Contracts/UnmanagedTransactionInterface.php"
    
    click DB "https://github.com/neo4j-php/neo4j-php-client/tree/main/src/Databags"
    click SRF "https://github.com/neo4j-php/neo4j-php-client/blob/main/src/Formatter/SummarizedResultFormatter.php"
    click BOT "https://github.com/neo4j-php/neo4j-php-client/blob/main/src/Formatter/Specialised/BoltOGMTranslator.php"
    
    click CU "https://github.com/neo4j-php/neo4j-php-client/tree/main/src/Common"
    click PH "https://github.com/neo4j-php/neo4j-php-client/blob/main/src/ParameterHelper.php"
    click T "https://github.com/neo4j-php/neo4j-php-client/tree/main/src/Types"

    %% Styles
    classDef client fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef driver fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef auth fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef conn fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef trans fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef fmt fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
    classDef util fill:#fefefe,stroke:#ced4da,stroke-width:2px;
```
