# neeraj-ghodla/redis-om-node architecture

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

- Interactive diagram: https://gitdiagram.com/neeraj-ghodla/redis-om-node
- Repository: https://github.com/neeraj-ghodla/redis-om-node

## Overview

##### Main Components
- External Dependencies:
– Redis Server (Redis Stack with RedisJSON and RediSearch)
– Node Redis client (used for connecting, executing commands, etc.)
- Library Core Modules (located in the “lib” directory):
– Client Module: (lib/client)
- Manages Redis connection, low‑level commands execution.
– Schema Module: (lib/schema)
- Defines the mappings for Entities (fields, types, optional JSONPath/field aliases).
– Entity Module: (lib/entity)
- Represents user entities as JavaScript objects with additional metadata (like the generated unique ID).
– Repository Module: (lib/repository)
- Provides a high‑level interface for data operations (saving, fetching, deleting, expiring, indexing, etc.).
– Search Module: (lib/search)
- Implements the fluent API for building RediSearch queries (numeric comparisons, full‑text search, geo‑search, pagination, sorting).
– Indexer Module: (lib/indexer)
- Responsible for building and maintaining search indexes based on Schema definitions.
– Transformer Module: (lib/transformer)
- Converts between different Redis data formats (e.g. JSON documents versus hashes) and JavaScript objects.
– Error Module: (lib/error)
- Contains custom error classes (such as “InvalidInput”, “InvalidSchema”, “SearchError”, etc.) that encapsulate various exception conditions.
- Tests & Documentation:
– Spec folder (spec) shows a comprehensive suite of unit and functional tests.
– Docs folder contains markdown documentation for each of the key classes (which can be referenced for details on public APIs).

##### Interactions and Relationships
- The User (or developer’s application) makes calls to the Repository.
- The Repository interacts with:
– The Client (to perform Redis operations via Node Redis)
– The Schema (to map data structures and enforce validations)
– The Indexer (to create or update search indexes when saving/updating Entities)
– The Transformer (to convert between JavaScript objects and Redis JSON/Hashes)
– The Search Module (to enable fluent query building and execution).
- Meanwhile, errors raised by any module (Client, Schema, or Indexer) are standardized via the Error Module.
- The Repository also provides methods for “search”, “save”, “update”, “fetch”, “remove”, and “expire” that internally combine these components.

##### Architectural Patterns & Design Principles
- Modular Design: The library is separated into distinct concerns (client, entity, schema, repository, search, iterator, transformer) which makes it both maintainable and testable.
- Fluent Interface: The search queries use a fluent API that allows chaining methods to build complex queries (as seen in the README examples).
- Abstraction over Redis: By encapsulating Redis operations within higher‑level abstractions (repository, transformer, etc.), the library hides the low‑level details from the developer.

##### Technologies and Frameworks
- Written in TypeScript.
- Uses Node Redis as an underlying Redis client.
- Integrates with Redis Stack components (RedisJSON, RediSearch, Geo features).
- Testing is performed with Vitest (as indicated by “vitest.config.js”) and additional TypeScript configurations (tsconfig.json).

## Diagram (Mermaid)

```mermaid
graph TD
    %% External Dependencies
    subgraph "External Dependencies"
        RS("Redis Server"):::external
        NR("Node Redis Client"):::external
    end

    %% Core Modules
    subgraph "Core Modules"
        CL("Client Module"):::core
        SC("Schema Module"):::core
        EN("Entity Module"):::core
        RE("Repository Module"):::core
        SE("Search Module"):::core
        IN("Indexer Module"):::core
    end

    %% Utility Modules
    subgraph "Utility Modules"
        TR("Transformer Module"):::utils
        ER("Error Module"):::utils
    end

    %% Testing and Documentation
    subgraph "Testing & Documentation"
        DO("Documentation"):::external
        TS("Tests"):::external
    end

    %% External User
    US("Developer/Application"):::external

    %% Interactions
    US -->|"calls"| RE
    RE -->|"issues Redis commands"| CL
    RE -->|"maps and validates"| SC
    RE -->|"converts data"| TR
    RE -->|"builds queries"| SE
    RE -->|"manages indexes"| IN
    RE -->|"utilizes entity definitions"| EN

    CL -->|"executes commands"| NR
    CL -->|"connects to"| RS

    SC -->|"defines structure for"| EN

    %% Error propagation from modules
    CL -->|"error"| ER
    SC -->|"error"| ER
    IN -->|"error"| ER

    %% Style for vertical spacing (using invisible nodes if needed for spacing)
    RE --- TR

    %% Classes
    classDef external fill:#f9f,stroke:#333,stroke-width:2px;
    classDef core fill:#bbf,stroke:#333,stroke-width:2px;
    classDef utils fill:#fc9,stroke:#333,stroke-width:2px;

    %% Click Events
    click CL "https://github.com/neeraj-ghodla/redis-om-node/blob/main/lib/client/client.ts"
    click SC "https://github.com/neeraj-ghodla/redis-om-node/blob/main/lib/schema/schema.ts"
    click EN "https://github.com/neeraj-ghodla/redis-om-node/blob/main/lib/entity/entity.ts"
    click RE "https://github.com/neeraj-ghodla/redis-om-node/blob/main/lib/repository/repository.ts"
    click SE "https://github.com/neeraj-ghodla/redis-om-node/blob/main/lib/search/search.ts"
    click IN "https://github.com/neeraj-ghodla/redis-om-node/blob/main/lib/indexer/index.ts"
    click TR "https://github.com/neeraj-ghodla/redis-om-node/blob/main/lib/transformer/index.ts"
    click ER "https://github.com/neeraj-ghodla/redis-om-node/blob/main/lib/error/index.ts"
    click DO "https://github.com/neeraj-ghodla/redis-om-node/tree/main/docs"
    click TS "https://github.com/neeraj-ghodla/redis-om-node/tree/main/spec"
```
