# neo4j-php/bolt architecture

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

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

## Overview

##### Component Relationships

**[Client Application] → [Bolt Factory]**
- ↓
**[Connection Layer] ← → [Protocol Layer] ← → [PackStream Layer]**

**[Socket Types]        [Protocol Versions]    [Serialization]**

##### Detailed Component Breakdown

Connection Layer (Green):
**┌─ Connection Interface (IConnection)**
- Socket Implementation
- StreamSocket Implementation
- PStreamSocket Implementation

Protocol Layer (Blue):
**┌─ Abstract Protocol**
- Version Implementations (V1-V5.6)
- Message Handlers
- Server State Management

PackStream Layer (Yellow):
**┌─ Packer Interface**
- Unpacker Interface
- Dictionary Generator
- List Generator

##### Implementation Details

Following flows:
**1. Connection Establishment:**
**Client → Handshake → Version Negotiation → Authentication**

**2. Query Execution:**
**Query → Protocol Version → PackStream → Socket → Neo4j Server**

**3. Response Handling:**
**Server Response → Socket → Unpacker → Protocol → Client**

##### Technical Notes

Annotations for:
- Supported Bolt versions (≤ 5.6)
- PHP version requirements (^8.1)
- Required extensions (mbstring, sockets, openssl)
- Connection timeout handling
- Server state transitions

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Client
        CA[Client Application]
    end

    subgraph Core["Core Components"]
        BF["Bolt Factory"]:::core
        click BF "https://github.com/neo4j-php/Bolt/blob/master/src/Bolt.php"
    end

    subgraph Connection["Connection Layer"]
        CI["Connection Interface"]:::connection
        click CI "https://github.com/neo4j-php/Bolt/blob/master/src/connection/IConnection.php"
        SI["Socket Implementation"]:::connection
        click SI "https://github.com/neo4j-php/Bolt/blob/master/src/connection/Socket.php"
        SSI["StreamSocket Implementation"]:::connection
        click SSI "https://github.com/neo4j-php/Bolt/blob/master/src/connection/StreamSocket.php"
        PSI["PStreamSocket Implementation"]:::connection
        click PSI "https://github.com/neo4j-php/Bolt/blob/master/src/connection/PStreamSocket.php"
    end

    subgraph Protocol["Protocol Layer"]
        AP["Abstract Protocol"]:::protocol
        click AP "https://github.com/neo4j-php/Bolt/blob/master/src/protocol/AProtocol.php"
        PV["Protocol Versions"]:::protocol
        click PV "https://github.com/neo4j-php/Bolt/blob/master/src/protocol/V1.php"
        MH["Message Handlers"]:::protocol
        SSM["Server State Management"]:::protocol
        click SSM "https://github.com/neo4j-php/Bolt/blob/master/src/protocol/v1/ServerStateTransition.php"
    end

    subgraph PackStream["PackStream Layer"]
        PI["Packer Interface"]:::packstream
        click PI "https://github.com/neo4j-php/Bolt/blob/master/src/packstream/IPacker.php"
        UI["Unpacker Interface"]:::packstream
        click UI "https://github.com/neo4j-php/Bolt/blob/master/src/packstream/IUnpacker.php"
        DG["Dictionary Generator"]:::packstream
        LG["List Generator"]:::packstream
    end

    subgraph Error["Error Handling"]
        BE["Bolt Exception"]:::error
        click BE "https://github.com/neo4j-php/Bolt/blob/master/src/error/BoltException.php"
        CE["Connect Exception"]:::error
        click CE "https://github.com/neo4j-php/Bolt/blob/master/src/error/ConnectException.php"
        PE["Pack Exception"]:::error
        click PE "https://github.com/neo4j-php/Bolt/blob/master/src/error/PackException.php"
        UE["Unpack Exception"]:::error
        click UE "https://github.com/neo4j-php/Bolt/blob/master/src/error/UnpackException.php"
    end

    subgraph Messages["Message System"]
        MT["Message Types"]:::message
        click MT "https://github.com/neo4j-php/Bolt/blob/master/src/enum/Message.php"
        SS["Server State"]:::message
        click SS "https://github.com/neo4j-php/Bolt/blob/master/src/enum/ServerState.php"
        MS["Message Signatures"]:::message
        click MS "https://github.com/neo4j-php/Bolt/blob/master/src/enum/Signature.php"
    end

    subgraph Structures["Structure Layer"]
        SI2["Structure Interface"]:::structure
        click SI2 "https://github.com/neo4j-php/Bolt/blob/master/src/protocol/IStructure.php"
        V1S["V1 Structures"]:::structure
        click V1S "https://github.com/neo4j-php/Bolt/tree/master/src/protocol/v1/structures"
        V5S["V5 Structures"]:::structure
        click V5S "https://github.com/neo4j-php/Bolt/tree/master/src/protocol/v5/structures"
    end

    %% Relationships
    CA --> BF
    BF --> CI
    CI --> SI & SSI & PSI
    BF --> AP
    AP --> PV
    AP --> MH
    AP --> SSM
    PV --> PI & UI
    PI --> DG
    PI --> LG

    %% Error Handling Relationships
    BE --> CE & PE & UE
    
    %% Message System Relationships
    MH --> MT
    MH --> SS
    MH --> MS

    %% Structure Relationships
    AP --> SI2
    SI2 --> V1S & V5S

    %% Styling
    classDef core fill:#3498db,stroke:#2980b9,color:white
    classDef connection fill:#2ecc71,stroke:#27ae60,color:white
    classDef protocol fill:#3498db,stroke:#2980b9,color:white
    classDef packstream fill:#f1c40f,stroke:#f39c12,color:black
    classDef error fill:#e74c3c,stroke:#c0392b,color:white
    classDef message fill:#f1c40f,stroke:#f39c12,color:black
    classDef structure fill:#9b59b6,stroke:#8e44ad,color:white

    %% Legend
    subgraph Legend
        L1[Core Components]:::core
        L2[Connection Components]:::connection
        L3[Protocol Components]:::protocol
        L4[PackStream Components]:::packstream
        L5[Error Components]:::error
        L6[Message Components]:::message
        L7[Structure Components]:::structure
    end
```
