# slashdb/js-slashdb architecture

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

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

## Overview

This repo is a **JavaScript ES6 SDK** (a client library), not a deployed “system” by itself. Its purpose is to help an application (browser or Node) **authenticate to a SlashDB instance** and then call two major SlashDB feature areas:

- **Data Discovery** (REST over database resources: tables/views/etc.)
- **SQL Pass-Thru** (execute predefined queries via SlashDB)

##### What the file tree tells you (map code to components)
Top-level:
- `src/` = the SDK modules (core of the product)
- `tests/` = Jest unit tests (verifies module behavior; not runtime architecture but good for component boundaries)
- `docs/` = generated JSDoc (confirms public APIs / classes)
- Build/tooling: `.babelrc`, `package.json`, `jest.config.js`, `jsdoc.conf.json`

Inside `src/`, the architecture is clearly layered:

##### Public API surface (what consumers import)
- `src/index.js` (barrel export)
- `src/slashdbclient.js` (entry point / session/auth/config)
- `src/datadiscovery.js` (DataDiscoveryDatabase, DataDiscoveryResource)
- `src/datadiscoveryfilter.js` (DataDiscoveryFilter URL/options builder)
- `src/sqlpassthru.js` (SQLPassThruQuery)
- `src/sqlpassthrufilter.js` (SQLPassThruFilter URL/options builder)
- `src/filterfunctions.js` (composable filter DSL helpers like `eq`, `any`, `and`, `asc/desc`)

##### Internal foundations (supporting layers)
- `src/baserequesthandler.js` (shared request execution logic)
- `src/fetchwrapper.js` (HTTP fetch abstraction)
- `src/basefilter.js` (shared filter builder primitives)
- `src/pkce.js` (SSO / OAuth PKCE support)
- `src/utils.js` (shared helpers)

This strongly suggests drawing it as:
**App → SDK public modules → internal request/filter utilities → HTTP → SlashDB**

##### Login/auth
- API key based login OR username/password login
- SSO login (with PKCE + redirect/popup)

##### Data Discovery call flow
- Create `SlashDBClient` (host + auth)
- Instantiate `DataDiscoveryDatabase`
- Instantiate `DataDiscoveryResource`
- Build `DataDiscoveryFilter`
- Call `resource.get/post/put/delete(filter)` → HTTP to SlashDB

##### SQL Pass-Thru call flow
- Create `SQLPassThruQuery(name, client)`
- Build `SQLPassThruFilter(params).limit().sort()...`
- Call `query.accept('csv').get(filter)` → HTTP to SlashDB

##### Consumer Application
- Browser app (examples/*.html) and/or Node app
##### SDK Package: @slashdb/js-slashdb
- Public modules:
- SlashDBClient
- DataDiscoveryDatabase
- DataDiscoveryResource
- DataDiscoveryFilter
- SQLPassThruQuery
- SQLPassThruFilter
- filterfunctions (eq/any/between/and/asc/desc…)
- Internal modules:
- BaseRequestHandler
- FetchWrapper
- BaseFilter
- PKCE
- Utils

**External systems**
##### SlashDB Server (external)
- Data Discovery REST endpoints
- SQL Pass-Thru endpoints
- Auth/SSO endpoints (IdP mediated)

##### Identity Provider (optional, external)
- Okta/etc (SSO), via PKCE redirect/popup

- `DataDiscoveryResource` → `BaseRequestHandler` (uses shared request logic)
- `SQLPassThruQuery` → `BaseRequestHandler`
- `DataDiscoveryFilter` → `BaseFilter` + `filterfunctions`
- `SQLPassThruFilter` → `BaseFilter` (or equivalent shared logic)
- `SlashDBClient` → `FetchWrapper` + `PKCE` + `Utils`
- `BaseRequestHandler` → `FetchWrapper`

- Consumer App → `SlashDBClient.login()` → (HTTP) → SlashDB auth endpoints
- Consumer App → `DataDiscoveryResource.get(filter)` → BaseRequestHandler → FetchWrapper → (HTTP) → SlashDB Data Discovery endpoints
- Consumer App → `SQLPassThruQuery.get(filter)` → BaseRequestHandler → FetchWrapper → (HTTP) → SlashDB SQL Pass-Thru endpoints
- If SSO: `SlashDBClient.login()` → PKCE → browser redirect/popup → IdP → SlashDB

- Data Discovery: typically JSON (but accept types exist)
- SQL Pass-Thru: may return CSV/JSON/etc depending on `.accept(...)`

##### Architectural patterns used

- **Layering**: public domain objects (Client/Resource/Query) on top of shared request + fetch abstraction.
- **Builder pattern**: `DataDiscoveryFilter` / `SQLPassThruFilter` are fluent option builders producing URL/query configuration.
- **Facade**: `SlashDBClient` hides auth/session/config mechanics (including SSO/PKCE).
- **Transport abstraction**: `FetchWrapper` isolates `fetch` usage for testability/environment differences.

##### Relevant technologies that matter
- ES6 modules
- `fetch` (via wrapper)
- Jest (tests) and JSDoc (docs) — tooling lane, not runtime lane
- PKCE for SSO

##### (Optional) SSO login (PKCE redirect/popup loop)

These sequences will make it obvious what’s synchronous/async, where HTTP happens, and what objects are responsible.

**Public**
- `SlashDBClient`
- `DataDiscoveryDatabase`
- `DataDiscoveryResource`
- `DataDiscoveryFilter`
- `SQLPassThruQuery`
- `SQLPassThruFilter`
- `filterfunctions` (eq/any/between/gte/lte/not/and/asc/desc/chgPlaceHolder)

**Internal**
- `BaseRequestHandler`
- `FetchWrapper`
- `BaseFilter`
- `PKCE`
- `Utils`

**External**
- SlashDB server:
- Auth endpoints
- Data Discovery endpoints
- SQL Pass-Thru endpoints
- (Optional) Identity Provider (Okta/etc)

Title it something like:
- **“js-slashdb SDK Architecture & Runtime Interactions”**
And put a subtitle:
- “Client-side library used by apps to authenticate and call SlashDB Data Discovery and SQL Pass-Thru APIs.”

That framing prevents reviewers from expecting deployable services inside this repo, while still being “system design accurate.”

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Title
    T["js-slashdb SDK Architecture & Runtime Interactions"]:::title

    %% =========================
    %% Consumer Applications
    %% =========================
    subgraph "Consumer Applications (Browser/Node)"
        direction TB
        App["Consumer Application"]:::consumer
        Demo["examples/demo.html"]:::consumer
        LoginDemo["examples/login_demo.html"]:::consumer
        Success["examples/success.html"]:::consumer
    end

    %% =========================
    %% SDK Package
    %% =========================
    subgraph "SDK Package: @slashdb/js-slashdb (ES6 Modules)"
        direction TB

        Index["Public API Barrel: index.js"]:::public

        subgraph "Public API Surface (what consumers import)"
            direction TB
            Client["SlashDBClient"]:::public

            subgraph "Data Discovery"
                direction TB
                DDB["DataDiscoveryDatabase"]:::public
                DDR["DataDiscoveryResource"]:::public
                DDF["DataDiscoveryFilter (builder)"]:::public
                FF["filterfunctions (DSL helpers)"]:::public
            end

            subgraph "SQL Pass-Thru"
                direction TB
                SPTQ["SQLPassThruQuery"]:::public
                SPTF["SQLPassThruFilter (builder)"]:::public
            end
        end

        subgraph "Internal Foundations (plumbing)"
            direction TB
            BRH["BaseRequestHandler"]:::internal
            FW["FetchWrapper (fetch abstraction)"]:::internal
            BF["BaseFilter (shared primitives)"]:::internal
            PKCE["PKCE (SSO OAuth PKCE)"]:::internal
            U["Utils"]:::internal
        end
    end

    %% =========================
    %% External Systems
    %% =========================
    subgraph "External Systems"
        direction TB

        subgraph "SlashDB Server (external)"
            direction TB
            SlashDB["SlashDB"]:::external
            AuthEP[("Auth Endpoints")]:::endpoint
            DDEP[("Data Discovery REST Endpoints")]:::endpoint
            SQLPTEP[("SQL Pass-Thru Endpoints")]:::endpoint
        end

        IdP["Identity Provider (Okta/etc)"]:::external
    end

    %% =========================
    %% Tooling / Non-runtime
    %% =========================
    subgraph "Tooling (non-runtime)"
        direction TB
        Tests["Jest Unit Tests"]:::tooling
        Docs["JSDoc Generated API Docs"]:::tooling
    end

    %% =========================
    %% Top-level alignment
    %% =========================
    T --> App
    App --> Index

    %% Consumer examples are concrete entrypoints into App usage
    Demo --> App
    LoginDemo --> App
    Success --> App

    %% =========================
    %% Dependency (import-time) relationships (dashed)
    %% =========================
    Index -.-> Client
    Index -.-> DDB
    Index -.-> DDR
    Index -.-> DDF
    Index -.-> SPTQ
    Index -.-> SPTF
    Index -.-> FF

    Client -.-> FW
    Client -.-> PKCE
    Client -.-> U

    DDR -.-> BRH
    SPTQ -.-> BRH
    BRH -.-> FW

    DDF -.-> BF
    DDF -.-> FF
    SPTF -.-> BF

    %% =========================
    %% Runtime call flows (solid)
    %% =========================
    %% Login/auth
    App -->|"calls login()"| Client
    Client -->|"HTTP auth"| FW
    FW -->|"HTTPS"| AuthEP

    %% Data Discovery flow
    App -->|"creates"| DDB
    App -->|"creates"| DDR
    App -->|"builds filter"| DDF
    App -->|"calls get/post/put/delete(filter)"| DDR
    DDR -->|"exec request"| BRH
    BRH -->|"uses fetch"| FW
    FW -->|"HTTPS (JSON/accept)"| DDEP

    %% SQL Pass-Thru flow
    App -->|"creates query(name, client)"| SPTQ
    App -->|"builds params/filter"| SPTF
    App -->|"calls accept(type).get(filter)"| SPTQ
    SPTQ -->|"exec request"| BRH
    FW -->|"HTTPS (CSV/JSON/etc)"| SQLPTEP

    %% Optional SSO/PKCE flow
    Client -->|"SSO login (optional)"| PKCE
    PKCE -->|"redirect/popup (browser)"| IdP
    IdP -->|"auth code/PKCE exchange"| AuthEP
    AuthEP -->|"session/token"| Client
    Success -->|"post-login landing"| App

    %% =========================
    %% Tooling relationships (dotted, non-runtime)
    %% =========================
    Tests -.-> Client
    Tests -.-> DDR
    Tests -.-> SPTQ
    Tests -.-> BRH
    Docs -.-> Index

    %% =========================
    %% Click events (component mapping)
    %% =========================
    click Index "https://github.com/slashdb/js-slashdb/blob/main/src/index.js"
    click Client "https://github.com/slashdb/js-slashdb/blob/main/src/slashdbclient.js"
    click DDB "https://github.com/slashdb/js-slashdb/blob/main/src/datadiscovery.js"
    click DDR "https://github.com/slashdb/js-slashdb/blob/main/src/datadiscovery.js"
    click DDF "https://github.com/slashdb/js-slashdb/blob/main/src/datadiscoveryfilter.js"
    click SPTQ "https://github.com/slashdb/js-slashdb/blob/main/src/sqlpassthru.js"
    click SPTF "https://github.com/slashdb/js-slashdb/blob/main/src/sqlpassthrufilter.js"
    click FF "https://github.com/slashdb/js-slashdb/blob/main/src/filterfunctions.js"
    click BRH "https://github.com/slashdb/js-slashdb/blob/main/src/baserequesthandler.js"
    click FW "https://github.com/slashdb/js-slashdb/blob/main/src/fetchwrapper.js"
    click BF "https://github.com/slashdb/js-slashdb/blob/main/src/basefilter.js"
    click PKCE "https://github.com/slashdb/js-slashdb/blob/main/src/pkce.js"
    click U "https://github.com/slashdb/js-slashdb/blob/main/src/utils.js"
    click Demo "https://github.com/slashdb/js-slashdb/blob/main/examples/demo.html"
    click LoginDemo "https://github.com/slashdb/js-slashdb/blob/main/examples/login_demo.html"
    click Success "https://github.com/slashdb/js-slashdb/blob/main/examples/success.html"
    click Tests "https://github.com/slashdb/js-slashdb/tree/main/tests/"
    click Docs "https://github.com/slashdb/js-slashdb/tree/main/docs/"

    %% =========================
    %% Styles (color required)
    %% =========================
    classDef title fill:#111827,stroke:#111827,color:#ffffff,stroke-width:2px
    classDef consumer fill:#d1fae5,stroke:#065f46,color:#064e3b,stroke-width:1.5px
    classDef public fill:#dbeafe,stroke:#1d4ed8,color:#1e3a8a,stroke-width:1.5px
    classDef internal fill:#e5e7eb,stroke:#374151,color:#111827,stroke-width:1.2px
    classDef external fill:#ffedd5,stroke:#9a3412,color:#7c2d12,stroke-width:1.5px
    classDef endpoint fill:#fed7aa,stroke:#c2410c,color:#7c2d12,stroke-width:1.2px
    classDef tooling fill:#ede9fe,stroke:#6d28d9,color:#3b0764,stroke-width:1.2px
```
