Installation Guide

Quality Hub GINEZ is a Next.js 14 application that uses Supabase for authentication, database, and real-time features. This guide walks you through setting up a complete instance from scratch.

Prerequisites

Before you begin, ensure you have:

Node.js 18+

Download from nodejs.org

Supabase Account

Google Sheets

For product catalog data (optional)

Google Drive

For technical documents storage (optional)

Installation Steps

Clone and install dependencies

Get the source code and install all required packages:

# Clone the repository
git clone <repository-url>
cd quality-hub-ginez

# Install dependencies
npm install

The project uses the following key dependencies:

Next.js 14 - React framework with App Router
@supabase/supabase-js - Supabase client library
@supabase/ssr - Server-side rendering support
Tailwind CSS - Utility-first CSS framework
shadcn/ui - High-quality React components
Recharts - Charting library for analytics

Create Supabase project

Go to supabase.com/dashboard
Click New Project
Choose your organization
Enter project details:
- Name: quality-hub-ginez
- Database Password: Generate a strong password
- Region: Choose closest to your users
Wait for the project to initialize (2-3 minutes)

Save your database password in a secure location. You’ll need it for direct database access.

Configure environment variables

Create a .env.local file in the project root:

cp .env.example .env.local

Then update the file with your actual values:

.env.local

# --- Google Sheets (Product Catalog CSV URLs) ---
SHEET_MP_CSV_URL="https://docs.google.com/spreadsheets/d/e/YOUR_ID/pub?gid=SHEET_ID_MP&single=true&output=csv"
SHEET_PT_CSV_URL="https://docs.google.com/spreadsheets/d/e/YOUR_ID/pub?gid=SHEET_ID_PT&single=true&output=csv"

# --- Next.js Configuration ---
NEXT_PUBLIC_BASE_PATH=""

# --- Supabase Configuration ---
# Get these from: https://supabase.com/dashboard/project/YOUR_PROJECT/settings/api
NEXT_PUBLIC_SUPABASE_URL="https://your-project.supabase.co"
NEXT_PUBLIC_SUPABASE_ANON_KEY="your-anon-key-here"

# --- Supabase Service Role (Server-side only, NEVER expose in frontend) ---
# SUPABASE_SERVICE_ROLE_KEY="your-service-role-key-here"

Never commit .env.local to version control. The .gitignore file should already exclude it, but always verify before pushing code.

Finding your Supabase credentials

Go to your Supabase project dashboard
Navigate to Settings → API
Copy the following:
- Project URL → NEXT_PUBLIC_SUPABASE_URL
- anon/public key → NEXT_PUBLIC_SUPABASE_ANON_KEY
- service_role key → SUPABASE_SERVICE_ROLE_KEY (optional, for server-side operations)

Setting up Google Sheets (Optional)

If you want to use Google Sheets for your product catalog:

Create a Google Sheet with your product data
Go to File → Share → Publish to web
Select the specific sheet and choose CSV format
Copy the published URL to your .env.local file

Set up the database schema

Run the database migrations to create all required tables and functions.

Core Tables

Execute these SQL commands in the Supabase SQL Editor:

-- Create profiles table
CREATE TABLE profiles (
  id UUID PRIMARY KEY REFERENCES auth.users(id) ON DELETE CASCADE,
  email TEXT,
  full_name TEXT,
  nombre TEXT,
  area TEXT,
  puesto TEXT,
  role TEXT DEFAULT 'preparador',
  sucursal TEXT,
  is_admin BOOLEAN DEFAULT false,
  created_at TIMESTAMPTZ DEFAULT NOW(),
  updated_at TIMESTAMPTZ DEFAULT NOW()
);

-- Create production logbook table
CREATE TABLE bitacora_produccion (
  id BIGSERIAL PRIMARY KEY,
  created_at TIMESTAMPTZ DEFAULT NOW(),
  lote_producto TEXT NOT NULL,
  codigo_producto TEXT NOT NULL,
  sucursal TEXT NOT NULL,
  familia_producto TEXT,
  categoria_producto TEXT,
  fecha_fabricacion DATE NOT NULL,
  tamano_lote NUMERIC,
  ph NUMERIC,
  solidos_medicion_1 NUMERIC,
  temp_med1 NUMERIC,
  solidos_medicion_2 NUMERIC,
  temp_med2 NUMERIC,
  viscosidad_seg NUMERIC,
  temperatura NUMERIC,
  apariencia TEXT,
  color TEXT,
  aroma TEXT,
  contaminacion_microbiologica TEXT,
  observaciones TEXT,
  nombre_preparador TEXT,
  user_id UUID REFERENCES auth.users(id),
  updated_at TIMESTAMPTZ DEFAULT NOW()
);

-- Enable Row Level Security
ALTER TABLE profiles ENABLE ROW LEVEL SECURITY;
ALTER TABLE bitacora_produccion ENABLE ROW LEVEL SECURITY;

Row Level Security Policies

-- Profiles: Users can view and update their own profile
CREATE POLICY "Users can view own profile"
ON profiles FOR SELECT
USING (auth.uid() = id);

CREATE POLICY "Users can update own profile"
ON profiles FOR UPDATE
USING (auth.uid() = id);

-- Bitacora: Users can view their own records
CREATE POLICY "Users can view own records"
ON bitacora_produccion FOR SELECT
USING (auth.uid() = user_id);

-- Bitacora: Admins can view all records
CREATE POLICY "Admins can view all records"
ON bitacora_produccion FOR SELECT
USING (
  EXISTS (
    SELECT 1 FROM profiles
    WHERE profiles.id = auth.uid()
    AND profiles.is_admin = true
  )
);

-- Bitacora: Users can insert their own records
CREATE POLICY "Users can insert own records"
ON bitacora_produccion FOR INSERT
WITH CHECK (auth.uid() = user_id);

-- Bitacora: Users can update their own records
CREATE POLICY "Users can update own records"
ON bitacora_produccion FOR UPDATE
USING (auth.uid() = user_id);

-- Bitacora: Admins can update all records
CREATE POLICY "Admins can update all records"
ON bitacora_produccion FOR UPDATE
USING (
  EXISTS (
    SELECT 1 FROM profiles
    WHERE profiles.id = auth.uid()
    AND profiles.is_admin = true
  )
);

-- Bitacora: Only admins can delete
CREATE POLICY "Admins can delete records"
ON bitacora_produccion FOR DELETE
USING (
  EXISTS (
    SELECT 1 FROM profiles
    WHERE profiles.id = auth.uid()
    AND profiles.is_admin = true
  )
);

These RLS policies ensure that regular users can only access their own data, while administrators have full access to all records.

Set up user roles and permissions (Advanced)

Quality Hub GINEZ includes a sophisticated role-based access control system. Run the role restructure migration:

-- This creates the role system with AC/AP/AR access levels
-- Located in: supabase/migrations/20260206_roles_restructure.sql

The system supports these roles:

admin - Full system access
preparador - Production staff
gerente_sucursal - Branch manager
director_operaciones - Operations director
gerente_calidad - Quality & development manager
mostrador - Counter staff
cajera - Cashier
director_compras - Purchasing director

Each role has specific access levels (AC/AP/AR) for each module with granular permissions:

can_view, can_download, can_create, can_edit, can_delete, can_export
available_filters - Allowed filter options
visible_tabs - Accessible tabs/sections

View complete role configuration

The role system defines permissions for these modules:

catalogo - Product catalog
bitacora - Production logbook
control_calidad - Quality control
reportes - Reports and analytics
configuracion - System configuration

Example permission for Preparador role:

{
  "module_key": "bitacora",
  "access_level": "AC",
  "can_view": true,
  "can_create": true,
  "can_edit": true,
  "can_delete": false,
  "available_filters": ["fecha", "categoria", "producto"],
  "visible_tabs": ["all"]
}

Create your first admin user

After setting up the database:

Sign up for an account through the app’s login page
Note the user’s email address
In Supabase SQL Editor, run:

-- Make a user an administrator
UPDATE profiles
SET is_admin = true, role = 'admin'
WHERE email = '[email protected]';

Always create at least one admin user before deploying to production. Without an admin, you won’t be able to manage other users through the UI.

Run the development server

Start the local development server:

npm run dev

Open http://localhost:3000 in your browser. You should see the login page.

The development server includes hot module replacement (HMR), so your changes will be reflected immediately without refreshing the page.

Build and deploy for production

When you’re ready to deploy:

npm run build
npm start

Deployment Options

Vercel (Recommended)
Docker
Self-hosted

Quality Hub GINEZ is optimized for Vercel deployment:

Push your code to GitHub
Import the project in Vercel
Add environment variables from .env.local
Deploy

Vercel automatically detects Next.js and configures build settings.

Create a Dockerfile:

FROM node:18-alpine AS base

# Dependencies
FROM base AS deps
RUN apk add --no-cache libc6-compat
WORKDIR /app
COPY package*.json ./
RUN npm ci

# Builder
FROM base AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build

# Runner
FROM base AS runner
WORKDIR /app
ENV NODE_ENV production

RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs

COPY --from=builder /app/public ./public
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static

USER nextjs
EXPOSE 3000
ENV PORT 3000

CMD ["node", "server.js"]

Build and run:

docker build -t quality-hub-ginez .
docker run -p 3000:3000 --env-file .env.local quality-hub-ginez

For self-hosted deployment on your own infrastructure:

Build the production bundle: npm run build
Copy the .next, public, and node_modules directories to your server
Set environment variables on the server
Run: npm start or use a process manager like PM2
Configure a reverse proxy (nginx/Apache) for HTTPS

Example PM2 configuration:

{
  "apps": [{
    "name": "quality-hub",
    "script": "npm",
    "args": "start",
    "env": {
      "NODE_ENV": "production",
      "PORT": 3000
    }
  }]
}

Post-Installation Configuration

Configure Authentication

In your Supabase project:

Go to Authentication → URL Configuration
Add your production domain to Site URL
Add redirect URLs for OAuth (if using social login)
Configure email templates under Email Templates

Set up Storage (Optional)

If you plan to store documents in Supabase Storage:

Go to Storage in Supabase dashboard
Create a bucket named documents
Set up storage policies for access control

Performance Optimization

Enable caching for Google Sheets data

The product catalog fetches from Google Sheets on every page load. For better performance:

// Add revalidation in your data fetching function
export const revalidate = 3600 // Cache for 1 hour

Optimize database queries

Add indexes for frequently queried columns:

CREATE INDEX idx_bitacora_user_id ON bitacora_produccion(user_id);
CREATE INDEX idx_bitacora_fecha ON bitacora_produccion(fecha_fabricacion);
CREATE INDEX idx_bitacora_sucursal ON bitacora_produccion(sucursal);
CREATE INDEX idx_profiles_role ON profiles(role);

Enable connection pooling

For high-traffic deployments, enable Supabase connection pooling:

Go to Database → Connection Pooling
Enable pooling mode
Use the pooled connection string for server-side operations

Verification Checklist

After installation, verify everything works:

Troubleshooting

Error: Invalid Supabase URL or key

Solution: Verify your environment variables are correctly set:

# Check if variables are loaded
console.log(process.env.NEXT_PUBLIC_SUPABASE_URL)

Make sure .env.local is in the project root and contains valid values.

RLS policy blocks all access

Solution: Check that your policies reference the correct columns and that auth.uid() returns the expected user ID.Debug with:

SELECT auth.uid(); -- Should return your user's UUID

Google Sheets data not loading

Solution: Ensure your sheets are:

Published to the web (File → Share → Publish to web)
Set to CSV format in the publish dialog
The URL ends with &single=true&output=csv

Build fails with TypeScript errors

Solution: Run type checking to see specific errors:

npx tsc --noEmit

Fix any type errors before building for production.

Next Steps

Quickstart Guide

Learn how to use the system as an end user

Architecture Overview

Understand the three-layer system architecture

Role Configuration

Customize roles and permissions for your organization

API Integration

Connect external systems via Supabase RPC functions

Need help? Check the project README at /workspace/source/README.md for detailed architecture information and implementation notes.

Quickstart

Production Logbook

⌘I

Get Started

Core Modules

Quality Management

User Management

Configuration

Prerequisites

Node.js 18+

Supabase Account

Google Sheets

Google Drive

Installation Steps

Finding your Supabase credentials

Setting up Google Sheets (Optional)

Core Tables

Row Level Security Policies

Deployment Options

Post-Installation Configuration

Configure Authentication

Set up Storage (Optional)

Performance Optimization

Verification Checklist

Troubleshooting

Next Steps

Quickstart Guide

Architecture Overview

Role Configuration

API Integration

Build docs developers (and LLMs) love

Get Started

Core Modules

Quality Management

User Management

Configuration

​Prerequisites

Node.js 18+

Supabase Account

Google Sheets

Google Drive

​Installation Steps

​Finding your Supabase credentials

​Setting up Google Sheets (Optional)

​Core Tables

​Row Level Security Policies

​Deployment Options

​Post-Installation Configuration

​Configure Authentication

​Set up Storage (Optional)

​Performance Optimization

​Verification Checklist

​Troubleshooting

​Next Steps

Quickstart Guide

Architecture Overview

Role Configuration

API Integration

Build docs developers (and LLMs) love

Prerequisites

Installation Steps

Finding your Supabase credentials

Setting up Google Sheets (Optional)

Core Tables

Row Level Security Policies

Deployment Options

Post-Installation Configuration

Configure Authentication

Set up Storage (Optional)

Performance Optimization

Verification Checklist

Troubleshooting

Next Steps