# aditya-ds-1806/dicedb-driver architecture

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

- Interactive diagram: https://gitdiagram.com/aditya-ds-1806/dicedb-driver
- Repository: https://github.com/aditya-ds-1806/dicedb-driver

## Overview

##### Project type and purpose
- This is a Node.js client library (driver) for DiceDB, an external in-memory database.
- Its goal is to expose a promise-based, high-performance API to send commands to DiceDB, manage connections, parse replies, and surface results or errors to the user.

##### File structure
- src/commands: individual Command classes (Set, Get, ZAdd, etc.) implementing each DiceDB protocol command.
- src/dicedb.ts + src/registry.ts: the main client class (DiceDBClient) and a registry mapping command Names to Command classes.
- lib/: compiled output (.js/.d.ts) mirroring core modules (Command, ConnectionPool, DiceDBSocket, Parsers, Validators).
- proto/ & dicedb-protos/: protocol buffer definitions and generated TypeScript types, used by Parsers to decode/encode wire messages.
- utils/: auxiliary Logger and helpers.
- scripts/codegen.ts: builds or updates the proto files.
- tests/ & examples/: validation and usage patterns.
- configuration and CI: .github/workflows, eslint.config.js, tsconfig.json, package.json.

##### Key README insights
- Emphasizes promise-based API, built-in connection pooling, clean modern interface.

##### Main components & interactions
a. User Application Layer
b. API / Client Layer
- DiceDBClient class (src/dicedb.ts): exposes connect(), disconnect(), and command methods.
- Registry: mapping of method names (ping, get, set…) to Command implementations.
c. Connection Pool
- ConnectionPool module: manages multiple logical connections for concurrency.
- Pool hands out Connection objects on each request.
d. Connection / Transport Layer
- DiceDBSocket: wraps a single TCP socket to the DiceDB server.
- Parsers: transforms incoming byte streams (using proto definitions) into JS objects or errors.
- Command instances: serialize user arguments into protocol buffers/messages.
e. Wire Protocol
- proto files (.proto, *.ts): message definitions, used by both codegen and parsers.
- scripts/codegen: generates TypeScript definitions, kept in proto/ and dicedb-protos/.
f. External Service
- DiceDB Server: remote host:port 7379.
g. Utilities & Support
- Validators: ensure arguments conform to protocol expectations before sending.
- Errors: custom error types returned on protocol or validation failures.
- Logger: optional instrumentation for debug/tracing.
h. Build & CI
- GitHub workflows: build, test, npm-publish.
- ESLint, TypeScript config, code coverage.

##### Architectural patterns & design principles
- Separation of concerns: API vs. pooling vs. transport vs. command serialization vs. parsing.
- Command pattern: each DiceDB command is a class implementing a uniform interface.
- Promise-based asynchronous flows: client methods return Promises resolved when parser completes.
- Code generation: proto→TypeScript ensures type-safe protocol handling.
- Layered design: user-facing → orchestration (pool) → transport → protocol.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Application Layer
    subgraph "User Application Layer"
        AppExamples["examples/"]:::user
        AppIndex["index.ts"]:::user
    end

    %% API / Client Layer
    subgraph "API / Client Layer"
        Client["DiceDBClient"]:::core
        CompiledCmd["Command (lib/Command.ts)"]:::core
    end

    %% Registry
    subgraph "Registry"
        RegistryTS["src/registry.ts"]:::core
        ConstCmd["src/constants/commands.ts"]:::core
    end

    %% Command Implementations
    subgraph "Command Pattern Implementations"
        CommandsDir["src/commands/"]:::core
    end

    %% Connection Pool
    subgraph "Connection Pool"
        Pool["ConnectionPool (lib/ConnectionPool.ts)"]:::core
    end

    %% Transport Layer
    subgraph "Connection / Transport Layer"
        Socket["DiceDBSocket"]:::transport
        Parsers["Parsers"]:::transport
        Validators["Validators"]:::transport
        Errors["Errors"]:::transport
    end

    %% Protocol Definitions & Codegen
    subgraph "Protocol Definitions & Codegen"
        ProtoDir["proto/"]:::protocol
        ProtoTsDir["dicedb-protos/"]:::protocol
        Codegen["scripts/codegen.ts"]:::protocol
    end

    %% Utilities & Support
    subgraph "Utilities & Support"
        Logger["utils/Logger.ts"]:::util
        Helpers["utils/index.ts"]:::util
    end

    %% Testing & Examples
    subgraph "Testing & Examples"
        Tests["tests/index.test.ts"]:::util
        Examples2["examples/"]:::user
    end

    %% Build, Lint & CI
    subgraph "Build, Lint & CI"
        CI1[".github/workflows/build.yml"]:::ci
        CI2[".github/workflows/test.yml"]:::ci
        CI3[".github/workflows/npm-publish.yml"]:::ci
        ESLint["eslint.config.js"]:::ci
        TSC["tsconfig.json"]:::ci
        PKG["package.json"]:::ci
    end

    %% External Service
    DB[("DiceDB Server")]:::external

    %% Connections
    AppExamples -->|"calls"| Client
    AppIndex -->|"calls"| Client

    Client -->|"uses registry"| RegistryTS
    Client -->|"uses compiled interface"| CompiledCmd
    RegistryTS -->|"maps commands"| CommandsDir
    ConstCmd --> RegistryTS

    CommandsDir -->|"validate args"| Validators
    CommandsDir -->|"serialize (protobuf)"| ProtoDir

    Client -->|"requests connection"| Pool
    Pool -->|"provides Connection"| Socket

    Socket -->|"sends/receives"| DB
    DB -->|"responses (bytes)"| Parsers
    Parsers -->|"parsed objects"| Client
    Parsers -->|"protocol errors"| Errors
    Validators -->|"validation errors"| Errors

    CommandsDir -->|"optional logging"| Logger
    Client -->|"logging calls"| Logger
    Helpers -->|"utilities used by"| CommandsDir

    Codegen -->|"generates definitions"| ProtoDir
    Codegen --> ProtoTsDir
    ProtoTsDir --> Parsers

    Tests -->|"tests"| Client
    Examples2 -->|"example usage"| Client

    CI1 -->|"runs build"| PKG
    CI2 -->|"runs tests"| Tests
    CI3 -->|"publishes"| PKG

    %% Click Events
    click AppExamples "https://github.com/aditya-ds-1806/dicedb-driver/tree/main/examples/"
    click AppIndex "https://github.com/aditya-ds-1806/dicedb-driver/blob/main/index.ts"
    click Client "https://github.com/aditya-ds-1806/dicedb-driver/blob/main/src/dicedb.ts"
    click CompiledCmd "https://github.com/aditya-ds-1806/dicedb-driver/blob/main/lib/Command.ts"
    click RegistryTS "https://github.com/aditya-ds-1806/dicedb-driver/blob/main/src/registry.ts"
    click ConstCmd "https://github.com/aditya-ds-1806/dicedb-driver/blob/main/src/constants/commands.ts"
    click CommandsDir "https://github.com/aditya-ds-1806/dicedb-driver/tree/main/src/commands/"
    click Pool "https://github.com/aditya-ds-1806/dicedb-driver/blob/main/lib/ConnectionPool.ts"
    click Socket "https://github.com/aditya-ds-1806/dicedb-driver/blob/main/lib/DiceDBSocket.ts"
    click Parsers "https://github.com/aditya-ds-1806/dicedb-driver/blob/main/lib/Parsers.ts"
    click Validators "https://github.com/aditya-ds-1806/dicedb-driver/blob/main/lib/Validators.ts"
    click Errors "https://github.com/aditya-ds-1806/dicedb-driver/blob/main/lib/Errors.ts"
    click ProtoDir "https://github.com/aditya-ds-1806/dicedb-driver/tree/main/proto/"
    click ProtoTsDir "https://github.com/aditya-ds-1806/dicedb-driver/tree/main/dicedb-protos/"
    click Codegen "https://github.com/aditya-ds-1806/dicedb-driver/blob/main/scripts/codegen.ts"
    click Logger "https://github.com/aditya-ds-1806/dicedb-driver/blob/main/utils/Logger.ts"
    click Helpers "https://github.com/aditya-ds-1806/dicedb-driver/blob/main/utils/index.ts"
    click Tests "https://github.com/aditya-ds-1806/dicedb-driver/blob/main/tests/index.test.ts"
    click Examples2 "https://github.com/aditya-ds-1806/dicedb-driver/tree/main/examples/"
    click CI1 "https://github.com/aditya-ds-1806/dicedb-driver/blob/main/.github/workflows/build.yml"
    click CI2 "https://github.com/aditya-ds-1806/dicedb-driver/blob/main/.github/workflows/test.yml"
    click CI3 "https://github.com/aditya-ds-1806/dicedb-driver/blob/main/.github/workflows/npm-publish.yml"
    click ESLint "https://github.com/aditya-ds-1806/dicedb-driver/blob/main/eslint.config.js"
    click TSC "https://github.com/aditya-ds-1806/dicedb-driver/blob/main/tsconfig.json"
    click PKG "https://github.com/aditya-ds-1806/dicedb-driver/blob/main/package.json"

    %% Styles
    classDef user fill:#ccf,stroke:#336,stroke-width:1px
    classDef core fill:#cfc,stroke:#363,stroke-width:1px
    classDef transport fill:#fdc,stroke:#ca6,stroke-width:1px
    classDef protocol fill:#fec,stroke:#c96,stroke-width:1px
    classDef util fill:#eee,stroke:#999,stroke-width:1px
    classDef ci fill:#cdf,stroke:#69c,stroke-width:1px
    classDef external fill:#f88,stroke:#d33,stroke-width:2px
```
