chatgpt-your-files: A Supabase Workshop for Building a Production Document Chat MVP

What This Workshop Builds and Who It Is For

chatgpt-your-files is a workshop repository from Supabase Community that teaches engineers to build a production-ready MVP for chatting with documents. The target user is a developer who understands the conceptual pieces of a retrieval-augmented generation (RAG) application but has not yet assembled them into a complete, deployable system with authentication, file storage, and database-level access control.

The application covers five concrete capabilities: a chat interface that queries documents using OpenAI's GPT models and RAG, third-party login through Supabase Auth with 18 supported providers, document upload and storage backed by Supabase Storage (S3 under the hood), a REST API consumed by the Next.js frontend, and row-level security to ensure each user can only access their own documents.

The repository includes three sample Markdown files in sample-files/ that contain Roman Empire history text: roman-empire-1.md, roman-empire-2.md, and roman-empire-3.md. These exist so a developer can test the full pipeline immediately after setup without needing to supply their own documents.

A complete recording of the workshop is available at the YouTube URL listed in the README, which covers the same material in video form for engineers who prefer to follow along with a presenter.

The Git Checkpoint Architecture

The workshop is structured as a sequence of git tags: step-0 through step-5, plus a bonus step. Each tag represents a complete state of the codebase at the end of one workshop stage. This design lets a developer jump to any point in the workshop without having to complete the preceding steps manually.

The recommended starting point is step-1, which includes the Storage feature:

git clone -b step-1 https://github.com/supabase-community/chatgpt-your-files.git

To advance to the next checkpoint during the workshop:

git stash push -u
git checkout step-X

The first command stashes any local changes including untracked files. The second checks out the target step. This pattern lets a developer experiment in the working directory between steps without losing progress, then jump forward cleanly when ready.

Step 5 is labeled as a bonus covering database type generation. The README instructs jumping to step-1 as the standard starting point, with step-0 available for those who want to see the additions made to a base create-next-app scaffold.

Setting Up the Local Supabase Stack

The workshop supports two Supabase environments: local development using Docker and a remote Supabase cloud project. For local development, the requirements are a Unix-based OS (WSL2 on Windows), Docker, and Node.js 18 or later.

Install npm dependencies first:

npm i

Start the local Supabase stack, which runs in Docker:

npx supabase start

Once running, write the API URL and anon key to the Next.js environment file:

npx supabase status -o env \
  --override-name api.url=NEXT_PUBLIC_SUPABASE_URL \
  --override-name auth.anon_key=NEXT_PUBLIC_SUPABASE_ANON_KEY | \
  grep NEXT_PUBLIC > .env.local

For the cloud path, create a Supabase project and link the CLI to it:

npx supabase projects create -i "ChatGPT Your Files"

The cloud path requires a Supabase account and a project ID from the dashboard. The README documents both paths step by step and provides the commands for both.

The Four Build Steps: Storage, Documents, Embeddings, and Chat

The workshop divides the application into four main feature steps, each building on the previous one.

Step 1 introduces Supabase Storage for file uploads. Supabase's object storage is backed by S3 and integrates with Postgres, so access control policies written in SQL apply to file access as well as database rows.

Step 2 adds document processing through Supabase Edge Functions. When a file is uploaded, a function processes its contents and prepares it for embedding. The Edge Functions runtime is Deno, and the import_map.json file in supabase/functions/ declares the Deno module dependencies.

Step 3 adds vector embeddings. The repository uses @xenova/transformers for generating embeddings and stores them in a pgvector column in Postgres. pgvector is Supabase's integrated vector extension, so no separate vector database is required.

Step 4 adds the chat interface. It uses the Vercel AI SDK and OpenAI's GPT models to generate responses grounded in the retrieved document chunks. The chat component uses @tanstack/react-query for state management and the Vercel AI SDK's streaming utilities to display partial responses as they arrive.

Each step has a corresponding git tag, so a developer who wants to study the embedding step without building from Storage can check out step-3 directly.

Row-Level Security and the Production-Ready Claim

The repository's description uses the phrase production-ready MVP. The production-readiness it delivers is specifically data isolation: Postgres row-level security policies ensure that each user can only read and write their own uploaded documents and generated embeddings, even if application-level bugs would otherwise allow cross-user access.

This is a concrete capability that a RAG prototype often omits. A naive implementation stores all users' documents in a shared table and relies on application code to filter by user ID. Row-level security moves that enforcement into the database, where it cannot be bypassed by a logic error in the application layer.

The workshop also covers third-party login through Supabase Auth, which supports 18 providers. The README does not specify which providers those are, but Supabase Auth is a documented feature of the Supabase platform, and the README does not enumerate the supported providers beyond the count.

Production-readiness here does not mean the application is ready to deploy without review. The dependencies, including the supabase CLI pinned at version 1.102.0, the OpenAI SDK, and the Vercel AI SDK, are at specific versions that may have known security issues or breaking changes in more recent releases.

What This Repository Does Not Cover

chatgpt-your-files is a workshop, not a configurable application framework. The embedding model, the LLM provider, the database backend, and the deployment target are all fixed: @xenova/transformers for embeddings, OpenAI for generation, Supabase for storage and auth, and Next.js as the frontend framework.

A developer who wants to use a different embedding model, a different vector store, or a Python backend will not find this repository adaptable by configuration. The code would need to be modified directly, and the workshop structure means the modifications cannot be isolated to a plugin layer.

The repository also does not cover reranking, hybrid search, chunking strategy tuning, or evaluation of retrieval quality. These are the concerns that typically separate an MVP from a production RAG system that handles diverse document types and user query patterns. Engineers who need guidance on those topics will need to look beyond this repository.

The sample files are Markdown documents. The workshop does not demonstrate how to handle PDFs, Word documents, or other binary document formats.

The repository also has no test suite. The package.json scripts include dev, build, start, and gen:types, but no test command. Engineers building on this foundation will need to add their own test coverage before treating the code as a production baseline.

The gen:types command generates TypeScript types from the local Supabase schema:

npm run gen:types

This is the bonus step from the workshop and produces a typed database client at supabase/functions/_lib/database.ts, giving the Edge Functions and the frontend accurate TypeScript types for the database schema without manual maintenance.

Alternative: LangChain for Multi-Provider and Python Environments

LangChain is a widely used framework for building LLM applications including RAG pipelines, available for both Python and JavaScript. Where chatgpt-your-files delivers a fixed architecture for one stack, LangChain provides composable building blocks that can be assembled with different embedding models, vector stores, and LLM providers.

The difference in approach is modularity versus completeness. LangChain requires the developer to wire together retrievers, embeddings, chains, and memory components. chatgpt-your-files provides all those components pre-wired and deployable, at the cost of being specific to Supabase, OpenAI, and Next.js. Engineers who need to switch providers or integrate with an existing Python data stack will find LangChain more adaptable. Engineers who want a working Next.js reference app they can study and deploy quickly, without building the authentication and storage layers from scratch, will find chatgpt-your-files more direct.

Editorial conclusion

chatgpt-your-files is well-suited to a TypeScript engineer who wants a complete working reference for a Supabase-backed RAG application and is willing to follow a workshop format to understand each layer. It is not a drop-in library or a configurable template: the application logic is specific to Supabase, OpenAI, and Next.js, and adapting it to a different backend or LLM provider requires rewriting rather than configuration. The last push was on 2026-05-12. Before using the code in production, verify that the dependency versions in package.json, particularly the Supabase CLI pinned at 1.102.0 and the OpenAI and Vercel AI SDK versions, are still supported and have no known security advisories.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. supabase-community/chatgpt-your-files on GitHub