# timelessco/recollect architecture

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

- Interactive diagram: https://gitdiagram.com/timelessco/recollect
- Repository: https://github.com/timelessco/recollect

## Overview

##### Project type and purpose
- Recollect is a full-stack web application built with Next.js on the frontend and Supabase on the backend.
- Purpose: allow users to add and manage bookmarks, images, and documents; assign them to collections (public or private); tag and search items; generate automatic image descriptions via AI; and optionally self-host.

##### File structure
- Top-level:
- public/ (static assets: SVGS, fonts)
- src/pages/ (Next.js pages and API routes)
- src/components/, src/pageComponents/ (React UI components & page-specific layouts)
- src/async/ (custom React Query hooks and Supabase CRUD helpers)
- src/utils/ (Supabase clients, API helpers, constants)
- cypress/ (end-to-end tests)
- env/ (environment/schema management)
- Next.js serverless functions under src/pages/api/ implement REST endpoints for bookmarks, categories, files, sharing, tags, settings, and AI (v1/ai/*).
- Two Supabase clients: supabaseClient (browser) and supabaseServerClient (server/API).
- CI/CD and self-hosting scripts (.github/actions, vercel.json, release-it).

##### Key architectural insights from README
- Frontend: React + Next.js with TypeScript, Tailwind CSS, hydration, SSR/ISR where needed.
- Backend: Supabase Auth, Postgres, Storage.
- AI: asynchronous OCR & embeddings via Supabase Edge functions and third-party APIs.
- Testing: Cypress end-to-end covering UI and API.
- Deployment: Vercel (serverless) or self-hosted.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client (Browser)"
        direction TB
        Components["Frontend UI Components"]:::frontend
        PageLayouts["Page-specific Layouts and Sections"]:::frontend
        Hooks["Custom Hooks (Client-side logic)"]:::frontend
        QueryHooks["React Query Data Hooks (Queries)"]:::frontend
        MutationHooks["React Query Data Hooks (Mutations)"]:::frontend
        CrudHelpers["Supabase CRUD Helpers"]:::frontend
        AIClient["AI Processing Helpers (Client)"]:::frontend
        UploadHelpers["File & Clipboard Upload Helpers"]:::frontend
        SupabaseBrowser["Supabase Browser Client"]:::frontend
    end

    %% Server Layer
    subgraph "Next.js Serverless" 
        direction TB
        Pages["Next.js Pages (SSR/ISR & Routing)"]:::backend
        APIRoutes["Next.js API Routes (REST endpoints)"]:::backend
        VersionedAPI["Versioned API & AI Endpoints"]:::backend
        SupabaseServer["Supabase Server Client"]:::backend
    end

    %% Supabase Services
    subgraph "Supabase Services"
        direction TB
        Auth["Auth"]:::backend
        DB["Postgres Database"]:::database
        Storage["Storage"]:::backend
        EdgeFunctions["Edge Functions (AI, OCR, Embeddings)"]:::backend
    end

    %% External Integrations
    subgraph "External Services"
        direction TB
        AIService["Third-party AI Service"]:::external
        EmailService["Email Service"]:::external
    end

    %% CI/CD & Testing
    subgraph "CI/CD & Testing"
        direction TB
        Cypress["Cypress End-to-End Tests"]:::infra
        GitHubActions["GitHub Actions Workflows"]:::infra
        Release["Release & Self-Host Scripts"]:::infra
    end

    %% Data Flows
    Components --> Hooks
    PageLayouts --> Hooks
    Hooks --> QueryHooks
    Hooks --> MutationHooks
    QueryHooks --> APIRoutes
    MutationHooks --> APIRoutes
    CrudHelpers --> APIRoutes
    AIClient --> VersionedAPI
    UploadHelpers --> APIRoutes
    SupabaseBrowser --> APIRoutes

    Pages --> SupabaseServer
    APIRoutes --> SupabaseServer
    VersionedAPI --> SupabaseServer

    SupabaseServer --> Auth
    SupabaseServer --> DB
    SupabaseServer --> Storage
    VersionedAPI --> EdgeFunctions
    EdgeFunctions --> DB
    EdgeFunctions --> Storage
    EdgeFunctions --> AIService

    APIRoutes --> EmailService

    DB --> Pages

    %% CI/CD & Testing Flows
    GitHubActions --> Pages
    GitHubActions --> APIRoutes
    GitHubActions --> Cypress
    GitHubActions --> Release
    Cypress --> APIRoutes
    Release --> Pages

    %% Click Events
    click Components "https://github.com/timelessco/recollect/tree/main/src/components/"
    click PageLayouts "https://github.com/timelessco/recollect/tree/main/src/pageComponents/"
    click Hooks "https://github.com/timelessco/recollect/tree/main/src/hooks/"
    click QueryHooks "https://github.com/timelessco/recollect/tree/main/src/async/queryHooks/"
    click MutationHooks "https://github.com/timelessco/recollect/tree/main/src/async/mutationHooks/"
    click CrudHelpers "https://github.com/timelessco/recollect/tree/main/src/async/supabaseCrudHelpers/"
    click AIClient "https://github.com/timelessco/recollect/tree/main/src/async/ai/"
    click UploadHelpers "https://github.com/timelessco/recollect/tree/main/src/async/uploads/"
    click Pages "https://github.com/timelessco/recollect/tree/main/src/pages/"
    click APIRoutes "https://github.com/timelessco/recollect/tree/main/src/pages/api/"
    click VersionedAPI "https://github.com/timelessco/recollect/tree/main/src/pages/api/v1/"
    click SupabaseBrowser "https://github.com/timelessco/recollect/blob/main/src/utils/supabaseClient.ts"
    click SupabaseServer "https://github.com/timelessco/recollect/blob/main/src/utils/supabaseServerClient.ts"
    click GitHubActions "https://github.com/timelessco/recollect/tree/main/.github/workflows/"
    click Release "https://github.com/timelessco/recollect/tree/main/release-it/"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef backend fill:#D0FFD8,stroke:#333,stroke-width:1px
    classDef database fill:#FFD0D0,stroke:#333,stroke-width:1px
    classDef external fill:#FFE8D0,stroke:#333,stroke-width:1px
    classDef infra fill:#F0F0F0,stroke:#333,stroke-width:1px
```
