# supabase/postgrest-js architecture

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

- Interactive diagram: https://gitdiagram.com/supabase/postgrest-js
- Repository: https://github.com/supabase/postgrest-js

## Overview

##### Main Components

a. Client Layer:
- PostgrestClient (core client class)
- Builder Classes:
- PostgrestQueryBuilder
- PostgrestFilterBuilder
- PostgrestTransformBuilder
- PostgrestBuilder (base class)

b. Query Processing Layer:
- Select Query Parser Component
- Parser
- Result Handler
- Type System

c. HTTP Communication Layer:
- Fetch Implementation (either cross-fetch or custom)
- Error Handling (PostgrestError)

##### Component Relationships

- Use a top-down approach showing data flow
- Client applications at the top
- PostgrestClient as the main entry point
- Builder classes branching from the client
- Query parser as a supporting component

##### Important Details

- Main operations (select, insert, update, delete)
- Isomorphic nature of the library
- Optional custom fetch implementation
- Type system integration

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Client_Applications
        APP[Client Application]
    end

    subgraph Core_Client
        PC["PostgrestClient"]:::core
        click PC "https://github.com/supabase/postgrest-js/blob/master/src/PostgrestClient.ts"
    end

    subgraph Builder_System
        PB["PostgrestBuilder<T>"]:::builder
        click PB "https://github.com/supabase/postgrest-js/blob/master/src/PostgrestBuilder.ts"
        
        QB["PostgrestQueryBuilder"]:::builder
        click QB "https://github.com/supabase/postgrest-js/blob/master/src/PostgrestQueryBuilder.ts"
        
        FB["PostgrestFilterBuilder"]:::builder
        click FB "https://github.com/supabase/postgrest-js/blob/master/src/PostgrestFilterBuilder.ts"
        
        TB["PostgrestTransformBuilder"]:::builder
        click TB "https://github.com/supabase/postgrest-js/blob/master/src/PostgrestTransformBuilder.ts"
    end

    subgraph Query_Parser
        direction TB
        QP[Select Query Parser]:::parser
        click QP "https://github.com/supabase/postgrest-js/tree/master/src/select-query-parser/"
        
        Parser[Parser Module]:::parser
        click Parser "https://github.com/supabase/postgrest-js/blob/master/src/select-query-parser/parser.ts"
        
        ResultHandler[Result Handler]:::parser
        click ResultHandler "https://github.com/supabase/postgrest-js/blob/master/src/select-query-parser/result.ts"
        
        TypeSystem[Type System]:::parser
        click TypeSystem "https://github.com/supabase/postgrest-js/blob/master/src/select-query-parser/types.ts"
        
        Utils[Utilities]:::parser
        click Utils "https://github.com/supabase/postgrest-js/blob/master/src/select-query-parser/utils.ts"
    end

    subgraph HTTP_Layer
        FI["Fetch Implementation"]:::http
        EH["Error Handler"]:::error
        click EH "https://github.com/supabase/postgrest-js/blob/master/src/PostgrestError.ts"
    end

    subgraph Types_And_Config
        TD["Type Definitions"]:::types
        click TD "https://github.com/supabase/postgrest-js/blob/master/src/types.ts"
        
        Constants["Constants"]:::types
        click Constants "https://github.com/supabase/postgrest-js/blob/master/src/constants.ts"
        
        Entry["Main Entry Point"]:::types
        click Entry "https://github.com/supabase/postgrest-js/blob/master/src/index.ts"
    end

    PGREST["PostgREST Server"]:::external

    %% Relationships
    APP --> PC
    PC --> PB
    PB --> |extends| QB
    PB --> |extends| FB
    PB --> |extends| TB
    
    QB & FB & TB --> QP
    QP --> Parser
    QP --> ResultHandler
    QP --> TypeSystem
    QP --> Utils
    
    QB & FB & TB --> FI
    FI --> |HTTP Requests| PGREST
    FI --> |Errors| EH
    
    PC -.-> TD
    PC -.-> Constants
    Entry -.-> PC

    %% Styles
    classDef core fill:#2196F3,stroke:#1565C0,color:white
    classDef builder fill:#4CAF50,stroke:#2E7D32,color:white
    classDef parser fill:#FFC107,stroke:#FFA000,color:black
    classDef http fill:#9C27B0,stroke:#7B1FA2,color:white
    classDef error fill:#F44336,stroke:#C62828,color:white
    classDef types fill:#607D8B,stroke:#455A64,color:white
    classDef external fill:#9E9E9E,stroke:#616161,color:white

    %% Legend
    subgraph Legend
        L1[Core Components]:::core
        L2[Builder Classes]:::builder
        L3[Parser Components]:::parser
        L4[HTTP Layer]:::http
        L5[Error Handling]:::error
        L6[Types & Config]:::types
        L7[External Systems]:::external
    end
```
