# millenniumdb/millenniumdb-driver-python architecture

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

- Interactive diagram: https://gitdiagram.com/millenniumdb/millenniumdb-driver-python
- Repository: https://github.com/millenniumdb/millenniumdb-driver-python

## Overview

##### Project Type and Purpose
- This is an open-source Python client library (driver) for MillenniumDB. It wraps network connection, message encoding/decoding, session management, and query result handling into a cohesive API. There’s no frontend or database code here—only client‐side logic interacting with an external server.

##### File Structure Analysis
- Top-level folders:
- docs/ – Sphinx documentation config
- src/millenniumdb_driver/ – core driver implementation
- Key modules under src:
- driver.py – entry point, factory for Driver instances
- session.py – manages sessions over a Driver (pool, lifecycle)
- socket_connection.py – raw TCP connection abstraction
- protocol.py, request_builder.py, message_encoder/decoder, receiver, response_handler – layered protocol stack
- catalog.py, graph_objects.py, record.py, result.py – domain object definitions

##### README Insights
- Describes usage: instantiate Driver → open Session → run queries → consume Result
- Emphasizes single connection per Driver, explicit close, and result‐consumption methods.

##### Components & Interactions
a. Application Layer
- Your client code imports millenniumdb_driver and calls driver()
b. Driver Component
- Driver Factory → holds Connection config
- Session Manager → issues Session instances
c. Connection & Protocol Stack
- SocketConnection → low-level TCP
- RequestBuilder → builds query messages
- MessageEncoder → serializes messages
- MessageReceiver → reads frames
- MessageDecoder → parses frames
- ResponseHandler → transforms into Result
d. Domain Objects
- Catalog, GraphObjects, Record, Result
- Data flows: ResponseHandler → Result → your code
e. External Service
- MillenniumDB Server (running elsewhere)

##### Architectural Patterns & Principles
- Layered protocol stack (builder → encode → send → receive → decode → handler)
- Factory (Driver → Session)
- Separation of concerns: transport, protocol, domain objects

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Application Layer
    subgraph "Application Layer"
        App["Client Application"]:::app
    end

    %% Driver Layer
    subgraph "Driver Layer"
        Driver["Driver Factory"]:::component
        Session["Session Manager"]:::component
        IObuf["I/O Buffer Utility"]:::component
        Errors["Error Definitions"]:::component
    end

    %% Protocol Stack
    subgraph "Protocol Stack"
        Builder["Request Builder\n(serialization)"]:::component
        Protocol["Protocol Definitions"]:::component
        Encoder["Message Encoder"]:::component
        Chunk["Chunk Decoder (framing)"]:::component
        Receiver["Message Receiver"]:::component
        Decoder["Message Decoder"]:::component
        Handler["Response Handler"]:::component
        Socket["Socket Connection"]:::network
    end

    %% Domain Objects
    subgraph "Domain Objects"
        Catalog["Catalog"]:::domain
        Graph["GraphObjects"]:::domain
        Record["Record"]:::domain
        Result["Result"]:::domain
    end

    %% External Service
    External["MillenniumDB Server"]:::external

    %% Connections
    App -->|"driver() call"| Driver
    Driver -->|"open() returns"| Session
    Session -->|"run(query)"| Builder
    Builder -->|"uses definitions"| Protocol
    Builder -->|"builds message"| Encoder
    Encoder -->|"writes to"| IObuf
    Encoder -->|"serialized frame"| Socket
    Socket -->|"TCP stream"| External
    External -->|"TCP stream"| Socket
    Socket -->|"raw bytes"| Chunk
    Chunk -->|"decoded frames"| Receiver
    Receiver -->|"reads from"| IObuf
    Receiver -->|"frame data"| Decoder
    Decoder -->|"message objects"| Handler
    Handler -->|"Result object"| Result
    Result -->|"records list"| App

    %% Error flows
    Builder --> Errors
    Encoder --> Errors
    Chunk --> Errors
    Receiver --> Errors
    Decoder --> Errors
    Handler --> Errors

    %% Click Events
    click Driver "https://github.com/millenniumdb/millenniumdb-driver-python/blob/main/src/millenniumdb_driver/driver.py"
    click Session "https://github.com/millenniumdb/millenniumdb-driver-python/blob/main/src/millenniumdb_driver/session.py"
    click Socket "https://github.com/millenniumdb/millenniumdb-driver-python/blob/main/src/millenniumdb_driver/socket_connection.py"
    click Protocol "https://github.com/millenniumdb/millenniumdb-driver-python/blob/main/src/millenniumdb_driver/protocol.py"
    click Builder "https://github.com/millenniumdb/millenniumdb-driver-python/blob/main/src/millenniumdb_driver/request_builder.py"
    click Encoder "https://github.com/millenniumdb/millenniumdb-driver-python/blob/main/src/millenniumdb_driver/request_builder.py"
    click Chunk "https://github.com/millenniumdb/millenniumdb-driver-python/blob/main/src/millenniumdb_driver/chunk_decoder.py"
    click Receiver "https://github.com/millenniumdb/millenniumdb-driver-python/blob/main/src/millenniumdb_driver/message_receiver.py"
    click Decoder "https://github.com/millenniumdb/millenniumdb-driver-python/blob/main/src/millenniumdb_driver/message_decoder.py"
    click Handler "https://github.com/millenniumdb/millenniumdb-driver-python/blob/main/src/millenniumdb_driver/response_handler.py"
    click Catalog "https://github.com/millenniumdb/millenniumdb-driver-python/blob/main/src/millenniumdb_driver/catalog.py"
    click Graph "https://github.com/millenniumdb/millenniumdb-driver-python/blob/main/src/millenniumdb_driver/graph_objects.py"
    click Record "https://github.com/millenniumdb/millenniumdb-driver-python/blob/main/src/millenniumdb_driver/record.py"
    click Result "https://github.com/millenniumdb/millenniumdb-driver-python/blob/main/src/millenniumdb_driver/result.py"
    click IObuf "https://github.com/millenniumdb/millenniumdb-driver-python/blob/main/src/millenniumdb_driver/iobuffer.py"
    click Errors "https://github.com/millenniumdb/millenniumdb-driver-python/blob/main/src/millenniumdb_driver/millenniumdb_error.py"

    %% Styles
    classDef component fill:#D0E8FF,stroke:#0D47A1,stroke-width:2px;
    classDef domain fill:#E8F5E9,stroke:#2E7D32,stroke-width:2px;
    classDef external fill:#FFF3E0,stroke:#EF6C00,stroke-width:2px;
    classDef network fill:#ECEFF1,stroke:#607D8B,stroke-width:2px;
    classDef app fill:#E3F2FD,stroke:#2196F3,stroke-width:2px;
```
