This section is for contributors working inside the Referenta monorepo. It mirrors the current repository workflow in the root README.md and explains how product changes move from isolated local development to reviewed production delivery.

Repository Layout

Referenta is a Turborepo-managed monorepo. Knowing where things live makes the rest of this setup easier to follow.

Applications

• apps/dashboard — the main Next.js web application that customers and team members use.
• apps/docs — the internal and external documentation site (the site you are reading).

Packages

• packages/ui — shared React component library consumed by the apps.
• packages/eslint-config — shared ESLint configuration.
• packages/typescript-config — shared TypeScript configuration.

Other

• api — Rust API that runs several Referenta core services.
• db — database schema and initialization files.
• db/migration — scripts that convert raw data for database migration.
• supabase/ — the supported Supabase CLI project at the repo root. The nested apps/dashboard/supabase/ folder is deprecated legacy config and must not be used for CLI commands.

Environment Model

Referenta uses a structured Supabase workflow with clear separation between local work, shared validation, and the live product. There are four environments in play:

• Local — Supabase CLI + Docker on your machine.
• Shared hosted dev — the existing hosted Supabase project (sknazmnmburyvxldoidy) for manual development and shared testing. Not auto-promoted.
• Staging — auto-deployed from the dev branch.
• Production — auto-deployed from the main branch.

dev is the only branch that deploys to staging. main is the only branch that deploys to production.

Local

Local development runs through the Supabase CLI and Docker. Each developer can start a full Supabase stack on their own machine, including the database, authentication, storage, and APIs.

Product impact:

• developers can experiment safely without changing shared data,
• schema changes can be validated before the team sees them, and
• iteration is faster because local reset, seeding, and testing are under the developer's control.

Technical impact:

• the repo root supabase/ directory is the supported Supabase CLI project,
• local schema work is generated into migrations,
• the dashboard can be pointed at http://127.0.0.1:54321, and
• local-only test users are created during reset for role-based testing.

Shared Validation

After local work is ready, migrations move into shared hosted environments for integration and team validation.

In practice, the repo distinguishes between:

• shared hosted development for linked remote work and manual testing,
• staging as the remote validation layer for approved dev branch changes, and
• production as the live environment used by customers.

This separation keeps collaboration predictable: local work stays isolated, while staging becomes the place where the team validates the same migration history together.

Production

Production only receives stable changes that have already been reviewed and validated. Direct edits in the dashboard or ad hoc schema changes are avoided in favor of committed migrations.

That gives Referenta:

• a traceable database history,
• repeatable environment setup,
• lower production risk, and
• clearer operational ownership over what changed and why.

Deploy Automation

GitHub Actions is the deploy source of truth:

• .github/workflows/ci.yml validates pushes to dev and main and all active pull requests.
• .github/workflows/preview-dashboard.yml deploys apps/dashboard preview builds for non-draft pull requests.
• .github/workflows/deploy-dashboard.yml deploys database migrations first when supabase/migrations/** changed, then deploys apps/dashboard with the Vercel CLI.

Because of this, merging a branch into dev automatically triggers a database deploy to staging, and merging into main automatically triggers a database deploy to production. Shared hosted dev is not auto-promoted.

Feature branch previews do not automatically push database migrations. If a feature branch includes database changes that need a working online database for review, manually push those migrations to the linked hosted dev project with pnpm db:push.

At a glance:

• Preview branches deploy dashboard previews only; database migrations are manual when needed.
• dev checks supabase/migrations/**, pushes migrations only when they changed, then deploys dashboard preview/staging.
• main checks supabase/migrations/**, pushes migrations only when they changed, then deploys dashboard production.

Migration-First Workflow

The expected progression is:

1. Build and test locally with the Docker-managed Supabase stack.
2. Generate or sync migrations from the local schema changes.
3. Commit those migrations into the repo.
4. Apply and validate them in shared remote environments.
5. Promote reviewed changes through staging and then production.

This is both a product workflow and an engineering guardrail. Product-wise, it prevents unreviewed infrastructure drift. Technically, it makes the repo history the source of truth for database evolution. See Database Workflow for the schema file layout and standard migration commands.

Contributor Setup

Prerequisites

Make sure you have the following installed:

• Node.js 24.x
• pnpm
• Vercel CLI
• Turborepo
• Supabase CLI
• Docker for the local Supabase stack

Clone And Install

git clone https://github.com/Referenta/referenta
cd referenta
git checkout dev
pnpm install

The dev branch is the default starting point because staging deploys from it and most active work lands there first.

Environment Variables From Vercel

To run the applications locally you'll need the hosted environment variables from Vercel.

1. Link the local repository to the Vercel project:

vercel link --repo

This command will guide you through connecting the monorepo to the corresponding project on Vercel.

2. Pull the development environment variables:

pnpm env:pull

This downloads the development environment variables from Vercel and creates .env files in the respective application directories.

Local Supabase Setup

Use the root supabase/ directory as the only supported Supabase CLI project for this repo.

1. Install the CLI dependency if needed:

pnpm add -Dw supabase

2. Authenticate and link the shared hosted development project once:

pnpm supabase:login
pnpm supabase:link:dev

This links the repo to shared dev project sknazmnmburyvxldoidy. pnpm supabase:link:dev requires a logged-in Supabase CLI session and the remote database password.

3. Pull the current remote baseline once:

pnpm db:pull -- remote_dev_baseline

This creates the baseline in supabase/migrations/. If the remote migration history does not match your local files yet, repair the linked history first and then run the pull again.

4. Start local Supabase and bootstrap the local database:

pnpm db:start
pnpm db:reset

pnpm db:reset applies the schema, runs the seed files, and creates one local-only account per role with password Referenta!2024#:

These accounts exist only in the local Docker-managed Supabase stack. They are not used for shared dev, staging, or production.

Point The Dashboard To Local Supabase

Copy apps/dashboard/.env.local.example to apps/dashboard/.env.local, then fill in the Supabase values from:

pnpm db:status:env

Map the output like this:

• API_URL -> NEXT_PUBLIC_SUPABASE_URL
• ANON_KEY -> NEXT_PUBLIC_SUPABASE_ANON_KEY
• PUBLISHABLE_KEY -> NEXT_PUBLIC_SUPABASE_PUBLISHABLE_DEFAULT_KEY
• SERVICE_ROLE_KEY -> SUPABASE_SERVICE_ROLE_KEY

Local vs remote, at a glance:

• Local Supabase — use apps/dashboard/.env.local with NEXT_PUBLIC_SUPABASE_URL=http://127.0.0.1:54321 and keys from pnpm db:status:env.
• Remote Supabase — run pnpm env:pull and keep the hosted Supabase values from Vercel.

Make Sure The Vercel .env Does Not Interfere

pnpm env:pull runs vercel env pull .env --environment=development, which writes to apps/dashboard/.env. That file holds the hosted dev credentials. You do not need to delete or rename it — Next.js takes care of precedence.

Next.js loads env files in this order, highest priority first:

1. .env.local — always wins (except in test mode)
2. .env.development.local
3. .env.development
4. .env — what pnpm env:pull just wrote

So any key you put in .env.local overrides the same key in .env. To keep the local stack isolated:

• Put only the four Supabase keys in .env.local. Do not redeclare unrelated keys (Sentry, analytics, third-party APIs) — let those keep coming from .env so the rest of the app still works.
• Restart the dev server after editing .env.local. Next.js reads env at process start; a running pnpm dev:dashboard will not pick up changes until you restart it.
• Verify the override took. The first Supabase request in your browser's network tab should hit 127.0.0.1:54321, not the hosted Supabase host. If it does not, the dev server was not restarted, or one of the keys is misspelled.

Switching back to remote later is just as cheap:

• Temporary toggle: rename .env.local to .env.local.disabled and restart. Values in .env take over.
• Permanent: delete .env.local. Recreate it next time you go local.

One thing to keep in mind: both .env and .env.local are gitignored, so neither leaks into the repo. But .env still contains hosted dev credentials even when the dashboard is pointed locally. Be careful copying values out of it for one-off shell commands like psql — those will hit shared Supabase, not your local stack.

Run The App

After the environment is ready, start the dashboard with:

pnpm dev:dashboard

This starts the Next.js development server on http://localhost:3000.

Included Pages