# holy-sheets/holysheets architecture

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

- Interactive diagram: https://gitdiagram.com/holy-sheets/holysheets
- Repository: https://github.com/holy-sheets/holysheets

## Overview

##### Main Components

a. Client Application Layer:
- How external applications interact with HolySheets!
- TypeScript interfaces for data models

b. HolySheets! Core Layer:
- Main HolySheets class as the entry point
- Base operations module
- Authentication handlers

c. Operation Handlers:
- CRUD operations (findFirst, findMany, insert, updateFirst, updateMany, etc.)
- Query builders and filters
- Data transformation utilities

d. Service Layer:
- Google Sheets Service
- Metadata Service
- Error handling service

e. External Services:
- Google Sheets API
- Authentication providers (JWT/OAuth2)

##### Component Relationships

**Client Application → HolySheets Core → Operation Handlers → Services → Google Sheets API**

##### Detailed Component Breakdown

Core Operations (src/core/):
- Similar operations (find*, update*, delete*, clear*)

Utilities (src/utils/):
- Supporting utilities:
- Column utilities
- Data utilities
- Range utilities
- Where filters
- Write operations

##### Specific Implementation Details

**TypeScript Interfaces:**
- User-defined types
- Operation configs
- Where filters
- Headers
- Cell values

**Service Interfaces:**
- IGoogleSheetsService
- IMetadataService

##### Data Flow Visualization

Typical flow of operations:

##### Key Design Patterns

Following patterns used:
- Factory pattern for operation creation
- Strategy pattern for different query types
- Service pattern for external integrations
- Builder pattern for query construction

##### Additional Elements

Include:
- Error handling flow
- Authentication flow
- Metadata collection points
- Type safety boundaries

##### Notes Section

Notes about:
- Type safety guarantees
- Authentication requirements
- Performance considerations
- Batch operation handling

Remember to emphasize the library's key features:
- A1 range abstraction
- CRUD operation simplification
- Type safety
- Metadata handling
- Error management
- Query filtering capabilities

This will create a comprehensive system design that accurately represents the HolySheets! library's architecture while maintaining clarity and usefulness for development teams.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Client["Client Application Layer"]
        App[Client Application]
        TypeDefs[Type Definitions]:::types
    end

    subgraph Core["HolySheets! Core Layer"]
        Entry["Main Entry Point"]:::core
        click Entry "https://github.com/holy-sheets/holysheets/blob/main/src/index.ts"
        
        subgraph Operations["Core Operations"]
            Find["Find Operations"]:::core
            click Find "https://github.com/holy-sheets/holysheets/tree/main/src/core/findFirst/"
            Update["Update Operations"]:::core
            click Update "https://github.com/holy-sheets/holysheets/tree/main/src/core/updateFirst/"
            Delete["Delete Operations"]:::core
            click Delete "https://github.com/holy-sheets/holysheets/tree/main/src/core/deleteFirst/"
            Clear["Clear Operations"]:::core
            click Clear "https://github.com/holy-sheets/holysheets/tree/main/src/core/clearFirst/"
            Insert["Insert Operation"]:::core
            click Insert "https://github.com/holy-sheets/holysheets/tree/main/src/core/insert/"
        end
    end

    subgraph Utils["Utility Layer"]
        ColumnUtils["Column Utilities"]:::utils
        click ColumnUtils "https://github.com/holy-sheets/holysheets/tree/main/src/utils/columnUtils/"
        DataUtils["Data Utilities"]:::utils
        click DataUtils "https://github.com/holy-sheets/holysheets/tree/main/src/utils/dataUtils/"
        RangeUtils["Range Utilities"]:::utils
        click RangeUtils "https://github.com/holy-sheets/holysheets/tree/main/src/utils/rangeUtils/"
        WhereUtils["Where Filter Utils"]:::utils
        click WhereUtils "https://github.com/holy-sheets/holysheets/tree/main/src/utils/where/"
        WriteUtils["Write Operations"]:::utils
        click WriteUtils "https://github.com/holy-sheets/holysheets/tree/main/src/utils/write/"
    end

    subgraph Types["Type Definitions"]
        CellValues["Cell Values"]:::types
        click CellValues "https://github.com/holy-sheets/holysheets/blob/main/src/types/cellValue.ts"
        Headers["Headers"]:::types
        click Headers "https://github.com/holy-sheets/holysheets/blob/main/src/types/headers.ts"
        OpConfigs["Operation Configs"]:::types
        click OpConfigs "https://github.com/holy-sheets/holysheets/blob/main/src/types/operationConfigs.ts"
        WhereFilters["Where Filters"]:::types
        click WhereFilters "https://github.com/holy-sheets/holysheets/blob/main/src/types/where.ts"
        Creds["Credentials"]:::types
        click Creds "https://github.com/holy-sheets/holysheets/blob/main/src/types/credentials.ts"
    end

    subgraph Services["Service Layer"]
        GSService["Google Sheets Service"]:::service
        click GSService "https://github.com/holy-sheets/holysheets/blob/main/src/services/google-sheets/GoogleSheetsService.ts"
        GSInterface["Google Sheets Interface"]:::service
        click GSInterface "https://github.com/holy-sheets/holysheets/blob/main/src/services/google-sheets/IGoogleSheetsService.ts"
        MetaService["Metadata Service"]:::service
        click MetaService "https://github.com/holy-sheets/holysheets/blob/main/src/services/metadata/MetadataService.ts"
        ErrorService["Error Handling"]:::service
        click ErrorService "https://github.com/holy-sheets/holysheets/tree/main/src/services/errors/"
    end

    subgraph External["External Services"]
        GSheetsAPI["Google Sheets API"]:::external
        Auth["Authentication"]:::external
    end

    %% Connections
    App --> Entry
    Entry --> Operations
    Operations --> Utils
    Operations --> Services
    Services --> External
    Utils --> Types
    Services --> Types

    %% Styles
    classDef core fill:#2196F3,color:white
    classDef service fill:#4CAF50,color:white
    classDef external fill:#FF9800,color:white
    classDef utils fill:#9C27B0,color:white
    classDef types fill:#757575,color:white

    %% Legend
    subgraph Legend
        L1["Core Components"]:::core
        L2["Services"]:::service
        L3["External Services"]:::external
        L4["Utilities"]:::utils
        L5["Types"]:::types
    end
```
