# andyruix1/db-sheets architecture

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

- Interactive diagram: https://gitdiagram.com/andyruix1/db-sheets
- Repository: https://github.com/andyruix1/db-sheets

## Overview

##### Project Type and Purpose
- This is an open-source Node.js / TypeScript library (“db-sheets”) whose sole responsibility is to provide a programmatic façade for Google Sheets.
- It exposes a single entry point (`SheetsManager`) that client code imports to connect, cache, read, write, update, and delete rows in Google Sheets.

##### File-Structure Analysis
- Top-level: configuration files (`package.json`, `tsconfig.json`, Jest, nodemon), build helper (`post-compile.ts`), lock files.
- `src/index.ts` exports the public API (`SheetsManager`).
- `src/lib/`: core modules –
- `Cache.ts` implements both “RAM” and “JSON file” caching strategies.
- `Sheet.ts` (or `SheetsManager`) contains the logic for all sheet operations.
- `help.ts` and `util.ts` hold low-level utilities (e.g., parsing cell coordinates, building request payloads).
- `src/types/`: TypeScript definitions for `Cache` and `Sheet`.

a. Client Application
– Imports and instantiates `SheetsManager` with credentials & options.
b. SheetsManager (API Layer / Facade)
– Exposes methods: `setSheetInfo()`, `getTableHeaders()`, `getTableValues()`, `insertValues()`, `updateValues()`, `deleteRowsByFilter()`.
c. Cache Layer
– Two modes: in-memory (fast) or JSON file (persistent).
– Controls fetch/update frequency to minimize Google API calls.
d. Google Sheets REST API
– External service that actually stores the spreadsheet data.
e. File System (optional)
– Stores JSON cache files when “saveMode: 'json'” is selected.

##### Interactions & Data Flow
1. Client → SheetsManager: calls an operation (e.g., `getTableValues`).
2. SheetsManager → Cache Layer: asks “do I have fresh data?”
– If yes → Cache returns JSON objects → SheetsManager returns to Client.
– If no → SheetsManager → Google Sheets API: sends HTTP request.
- Google responds with raw ranges.
- SheetsManager transforms them into JSON objects via `util.ts`.
- SheetsManager → Cache Layer: store updated data.
- SheetsManager → Client: returns JSON.
3. For write/update/delete, the reverse: Client → SheetsManager → Google Sheets API → update remote → update cache.

##### Architectural Patterns & Principles
- Facade Pattern: `SheetsManager` provides a simplified interface over the complex Google Sheets API.
- Strategy Pattern: `Cache.ts` chooses between RAM or JSON-file strategies.
- Single Responsibility: each module handles one concern (caching vs. sheet-operations vs. utilities).
- Modular & Pluggable: low-level utilities separated for testability and reuse.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    ClientApp["Client Application"]:::client

    %% Public API
    PublicAPI["Public API\n(src/index.ts)"]:::module
    click PublicAPI "https://github.com/andyruix1/db-sheets/blob/main/src/index.ts"

    %% Core Library Modules
    SheetsManager["SheetsManager Facade\n(src/lib/Sheet.ts)"]:::module
    click SheetsManager "https://github.com/andyruix1/db-sheets/blob/main/src/lib/Sheet.ts"

    CacheLayer["Cache Layer\n(RAM & JSON)\n(src/lib/Cache.ts)"]:::module
    click CacheLayer "https://github.com/andyruix1/db-sheets/blob/main/src/lib/Cache.ts"

    subgraph "Utilities"
        Util["Utility Functions\nParsing & Payload\n(src/lib/util.ts)"]:::module
        click Util "https://github.com/andyruix1/db-sheets/blob/main/src/lib/util.ts"
        Help["Helper Utilities\n(src/lib/help.ts)"]:::module
        click Help "https://github.com/andyruix1/db-sheets/blob/main/src/lib/help.ts"
    end

    %% External Services
    GoogleAPI["Google Sheets REST API"]:::external

    %% Persistent Storage
    JSONFS["JSON File System\n(optional)"]:::storage

    %% Project Config & Build
    subgraph "Build & Config"
        BuildHelper["Build Helper\n(post-compile.ts)"]:::module
        click BuildHelper "https://github.com/andyruix1/db-sheets/blob/main/post-compile.ts"
        PackageJSON["package.json"]:::module
        click PackageJSON "https://github.com/andyruix1/db-sheets/blob/main/package.json"
        TSConfig["tsconfig.json"]:::module
        click TSConfig "https://github.com/andyruix1/db-sheets/blob/main/tsconfig.json"
        JestConfig["jest.config.js"]:::module
        click JestConfig "https://github.com/andyruix1/db-sheets/blob/main/jest.config.js"
        NodemonConfig["nodemon.json"]:::module
        click NodemonConfig "https://github.com/andyruix1/db-sheets/blob/main/nodemon.json"
    end

    %% Data Flow
    ClientApp -->|"import & call"| PublicAPI
    PublicAPI -->|"delegates to"| SheetsManager

    SheetsManager -->|"check cache"| CacheLayer
    CacheLayer -.->|"cache hit: return JSON objects"| SheetsManager
    SheetsManager -->|"cache miss: fetch data"| GoogleAPI
    GoogleAPI -->|"returns raw ranges"| SheetsManager
    SheetsManager -->|"transform to JSON"| Util
    SheetsManager -->|"transform to JSON"| Help
    SheetsManager -->|"store updated data"| CacheLayer
    CacheLayer -->|"reads/writes JSON files"| JSONFS
    SheetsManager -->|"return JSON objects"| ClientApp

    %% Types (for reference)
    subgraph "TypeScript Definitions"
        CacheTypes["Cache Types\n(src/types/Cache.d.ts)"]:::module
        click CacheTypes "https://github.com/andyruix1/db-sheets/blob/main/src/types/Cache.d.ts"
        SheetTypes["Sheet Types\n(src/types/Sheet.d.ts)"]:::module
        click SheetTypes "https://github.com/andyruix1/db-sheets/blob/main/src/types/Sheet.d.ts"
    end

    %% Legend
    subgraph Legend
        direction LR
        A["Client Application"]:::client
        B["Library Module"]:::module
        C["External Service"]:::external
        D["Persistent Storage"]:::storage
    end

    classDef client fill:#cccccc,stroke:#333;
    classDef module fill:#ADD8E6,stroke:#333;
    classDef external fill:#90EE90,stroke:#333;
    classDef storage fill:#FFD700,stroke:#333;
```
