# andriishupta/nestjs-supabase-setup architecture

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

- Interactive diagram: https://gitdiagram.com/andriishupta/nestjs-supabase-setup
- Repository: https://github.com/andriishupta/nestjs-supabase-setup

## Overview

##### Project Type & Purpose
- This is a backend API project built with NestJS.
- Its primary purpose is to demonstrate how to integrate Supabase (v1) with NestJS, focusing on authentication and the creation of a request-scoped Supabase client.
- The README also points to setting up guards (using NestJS’s APP_GUARD mechanism) to secure routes via Supabase authentication.

##### Main Components to Highlight
- Client (or API Consumer): Represents the external system or user making HTTP requests with an access_token in the Authorization header.
- Controller Layer: This is where incoming HTTP requests are handled. In the file tree, the AppController in src/app.controller.ts is the entry point that routes requests.
- Service Layer: For business logic implementation; the AppService located in src/app.service.ts exemplifies this.
- NestJS Module: The AppModule (src/app.module.ts) orchestrates dependencies and organizes the overall application structure.
- Supabase Integration/Module: All Supabase-related functionality (authentication, client creation) is encapsulated in the supabase folder under src/common/supabase. This includes:
- The SupabaseModule (src/common/supabase/supabase.module.ts) for module-level configuration.
- The SupabaseGuard (src/common/supabase/supabase.guard.ts) which ensures that requests are authenticated.
- Supporting files like the index, strategy, and supabase.ts for client interaction and instantiation scoped to each request.
- NestJS Bootstrapping: The main entry point (src/main.ts) that initializes the NestJS application.
- Configuration & Environment: Files like .env.example indicate environment-specific configurations crucial for connecting to Supabase (credentials, tokens, etc.).

##### Relationships and Interactions
- The Client sends HTTP requests (with an access_token) to the API.
- The request first reaches the Controller, which then delegates processing to the Service layer.
- Before processing, the SUPABASE_GUARD (applied globally or per route) validates and injects the correct Supabase client instance using a request-scoped provider.
- The SupabaseModule encapsulates the logic of creating and managing the Supabase client, ensuring that each request receives its own context.
- The Service then uses the per-request Supabase client (via supabase.getClient()) to interact with Supabase (e.g., for data queries and authentication checks).

##### Architectural Patterns & Principles
- Dependency Injection: A core principle in NestJS is the injection of dependencies (like Supabase clients) to manage component lifecycles.
- Request Scoping: Particularly important here is the request-scoped provider for the Supabase client.
- Separation of Concerns: Clearly separates controller, service, and module logic. The Supabase integration is modularized within its own common directory.
- Global and Route-Specific Guards: Use of APP_GUARD to apply authentication globally or via decorators on specific routes.

##### Relevant Technologies & Frameworks
- NestJS for the core framework and architectural pattern.
- Supabase as the backend-as-a-service handling database and auth.
- TypeScript, as indicated by the tsconfig files.
- Testing frameworks (Jest based on the test folder) for e2e tests.
- Configuration tools such as ESLint, Prettier, and environment files for code quality and environment management.

- "Client (HTTP Request)"
- "NestJS Controller" (AppController)
- "NestJS Service" (AppService)
- "NestJS Module" (AppModule)
- "Supabase Module" encompassing:
- SupabaseGuard
- SupabaseStrategy
- Supabase Client Provider (per-request instance)
- "Configuration/Environment" for environment variables and .env file content.
- Optionally, show a return flow (response sent back to the client).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% App Initialization
    subgraph "App Initialization"
        Bootstrap["NestJS Bootstrapping (Application Entry Point)"]:::nestjs
        Module["NestJS Module (AppModule)"]:::nestjs
        Config["Configuration/Environment Settings"]:::config
        Config -- "providesConfig" --> Bootstrap
        Bootstrap --> Module
    end

    %% Request Handling
    subgraph "Request Handling"
        Client["Client (HTTP Request)"]:::external
        Controller["NestJS Controller (AppController)"]:::nestjs
        Service["NestJS Service (AppService)"]:::nestjs
        Client -->|"sendsAccessToken"| Controller
        Controller -->|"delegatesTo"| Service
    end

    %% Supabase Integration
    subgraph "Supabase Integration"
        SupabaseModule["Supabase Module (Module Configuration)"]:::supabase
        Guard["Supabase Guard (Authentication Guard)"]:::supabase
        Strategy["Supabase Strategy (Authentication/Client Handling)"]:::supabase
        ClientProvider["Supabase Client Provider (Per-request Client Instantiation)"]:::supabase
        SupabaseModule --> Guard
        SupabaseModule --> Strategy
        SupabaseModule --> ClientProvider
        Guard -->|"validates"| Strategy
    end

    %% Linking Modules with Request Handling and Supabase
    Module --> Controller
    Module --> SupabaseModule
    Controller -- "guardCheck" --> Guard
    Service -->|"requestsClient"| ClientProvider

    %% Styles
    classDef nestjs fill:#85C1E9,stroke:#1B4F72,stroke-width:2px;
    classDef supabase fill:#A9DFBF,stroke:#196F3D,stroke-width:2px;
    classDef external fill:#F9E79F,stroke:#D4AC0D,stroke-width:2px;
    classDef config fill:#D7BDE2,stroke:#6C3483,stroke-width:2px;

    %% Click Events
    click Controller "https://github.com/andriishupta/nestjs-supabase-setup/blob/main/src/app.controller.ts"
    click Service "https://github.com/andriishupta/nestjs-supabase-setup/blob/main/src/app.service.ts"
    click Module "https://github.com/andriishupta/nestjs-supabase-setup/blob/main/src/app.module.ts"
    click SupabaseModule "https://github.com/andriishupta/nestjs-supabase-setup/blob/main/src/common/supabase/supabase.module.ts"
    click Guard "https://github.com/andriishupta/nestjs-supabase-setup/blob/main/src/common/supabase/supabase.guard.ts"
    click Strategy "https://github.com/andriishupta/nestjs-supabase-setup/blob/main/src/common/supabase/supabase.strategy.ts"
    click ClientProvider "https://github.com/andriishupta/nestjs-supabase-setup/blob/main/src/common/supabase/supabase.ts"
    click ClientProvider "https://github.com/andriishupta/nestjs-supabase-setup/blob/main/src/common/supabase/index.ts"
    click Bootstrap "https://github.com/andriishupta/nestjs-supabase-setup/blob/main/src/main.ts"
    click Config "https://github.com/andriishupta/nestjs-supabase-setup/blob/main/.env.example"
```
