Installation

Prerequisites

Before you begin, ensure you have the following installed on your development machine:

Node.js

Version 18.x or higher

npm

Version 9.x or higher (comes with Node.js)

Git

For cloning the repository

Check your versions:

node --version
npm --version
git --version

Supabase Account Setup

PAE Inventory System uses Supabase for authentication and database. You’ll need to create a Supabase project:

Create Supabase Account

Go to supabase.com
Sign up for a free account
Verify your email address

Create New Project

Click New Project
Choose an organization (or create one)
Enter project details:
- Name: pae-inventory (or your preferred name)
- Database Password: Generate a strong password (save it securely!)
- Region: Choose the closest region to Venezuela
Click Create new project
Wait 2-3 minutes for provisioning

Get API Credentials

Once the project is ready:

Go to Settings → API
Copy these values (you’ll need them later):
- Project URL (looks like https://xxxxx.supabase.co)
- anon public key (under “Project API keys”)
- service_role key (under “Project API keys”)

Keep your service_role key secret! Never commit it to version control or expose it in client-side code.

Set Up Database Schema

Go to SQL Editor in your Supabase dashboard
Create a new query
Copy the entire contents of supabase_schema.sql from the repository
Paste and click Run
Wait for completion (may take 30-60 seconds)

This creates all tables, triggers, RLS policies, and sample data.

The schema file is located at /workspace/source/supabase_schema.sql in the repository.

Local Development Setup

Clone the Repository

Clone the source code to your local machine:

git clone <repository-url>
cd pae-inventory

Replace <repository-url> with the actual Git repository URL.

Install Dependencies

Install all required npm packages:

npm install

This installs the following key dependencies:

{
  "@supabase/supabase-js": "^2.39.0",
  "lucide-react": "^0.575.0",
  "react": "^18.2.0",
  "react-dom": "^18.2.0",
  "react-router-dom": "^6.21.0",
  "sweetalert2": "^11.26.20"
}

Dev dependencies include Vite, Tailwind CSS, and PostCSS.

Configure Environment Variables

Create a .env file in the project root:

touch .env

Add your Supabase credentials:

VITE_SUPABASE_URL=https://your-project.supabase.co
VITE_SUPABASE_ANON_KEY=your-anon-key-here
VITE_SUPABASE_SERVICE_ROLE_KEY=your-service-role-key-here

Replace the placeholder values with your actual Supabase credentials from Step 3 of Supabase setup.

The application reads these variables in src/supabaseClient.js:

// Obtener las variables de entorno
const supabaseUrl = import.meta.env.VITE_SUPABASE_URL
const supabaseAnonKey = import.meta.env.VITE_SUPABASE_ANON_KEY
const supabaseServiceRoleKey = import.meta.env.VITE_SUPABASE_SERVICE_ROLE_KEY

// Validar que existan
if (!supabaseUrl || !supabaseAnonKey) {
  console.error('ERROR: Faltan variables de entorno de Supabase')
  console.log('Asegúrate de tener un archivo .env con VITE_SUPABASE_URL y VITE_SUPABASE_ANON_KEY')
}

// Crear el cliente de Supabase
export const supabase = createClient(supabaseUrl, supabaseAnonKey)

Create Initial Admin User

You need at least one Director user to access the system. Create one directly in Supabase:

Go to Authentication → Users in Supabase dashboard
Click Add user → Create new user
Enter:
- Email: [email protected]
- Password: Your secure password
- Auto Confirm User: ✅ Enable
Click Create user
Copy the User UID (you’ll need it next)

Now add the user to the users table:

Go to Table Editor → users
Click Insert row
Enter:
- id_user: Paste the User UID from above
- username: director
- full_name: Director Principal
- id_rol: 1 (Director role)
- is_active: true
Click Save

After the first Director account is created, you can create additional users from within the application.

Start Development Server

Launch the Vite development server:

npm run dev

You should see output like:

VITE v5.0.8  ready in 423 ms

➜  Local:   http://localhost:5173/
➜  Network: use --host to expose
➜  press h to show help

Open your browser to http://localhost:5173

You should see the login page
Enter the Director credentials you created
After successful login, you’ll see the Dashboard
Verify that all sections are accessible

If you see the Dashboard with navigation menu, congratulations! Your local development environment is ready.

Application Structure

Understanding the codebase organization:

pae-inventory/
├── public/                 # Static assets
├── src/
│   ├── components/        # Reusable React components
│   │   ├── Layout.jsx    # Main layout wrapper
│   │   ├── PrivateRoute.jsx  # Auth-protected route wrapper
│   │   ├── GlobalLoader.jsx  # Loading spinner
│   │   └── ...
│   ├── pages/            # Page components
│   │   ├── Login.jsx     # Login page
│   │   ├── Dashboard.jsx # Main dashboard
│   │   ├── Products.jsx  # Product management
│   │   ├── GuiasEntrada.jsx  # Delivery guides
│   │   ├── AprobarGuias.jsx  # Guide approval (Directors only)
│   │   ├── RegistroDiario.jsx # Daily operations
│   │   ├── Porciones.jsx # Portion yield configuration
│   │   ├── Reportes.jsx  # Reports
│   │   ├── AuditLog.jsx  # Audit trail viewer
│   │   ├── Usuarios.jsx  # User management (Directors only)
│   │   └── DatosPlantel.jsx  # School info
│   ├── App.jsx           # Main app component with routing
│   ├── supabaseClient.js # Supabase client and helpers
│   ├── main.jsx          # Application entry point
│   └── index.css         # Global styles (Tailwind)
├── supabase_schema.sql   # Complete database schema
├── package.json          # Dependencies and scripts
├── vite.config.js        # Vite configuration
├── tailwind.config.js    # Tailwind CSS configuration
├── postcss.config.js     # PostCSS configuration
└── .env                  # Environment variables (create this)

Key Files Explained

src/App.jsx

Main application component that sets up React Router and authentication:

import { BrowserRouter as Router, Routes, Route, Navigate } from 'react-router-dom'
import { useState, useEffect } from 'react'
import { supabase } from './supabaseClient'

function App() {
  const [session, setSession] = useState(null)
  const [loading, setLoading] = useState(true)

  useEffect(() => {
    // Obtener sesión actual
    supabase.auth.getSession().then(({ data: { session } }) => {
      setSession(session)
      setLoading(false)
    })

    // Escuchar cambios de autenticación
    const {
      data: { subscription },
    } = supabase.auth.onAuthStateChange((_event, session) => {
      setSession(session)
    })

    return () => subscription.unsubscribe()
  }, [])

  // ... routing logic
}

Defines all application routes including public (login) and private (dashboard, products, etc.) routes.

src/supabaseClient.js

Supabase client initialization and helper functions:

import { createClient } from '@supabase/supabase-js'

const supabaseUrl = import.meta.env.VITE_SUPABASE_URL
const supabaseAnonKey = import.meta.env.VITE_SUPABASE_ANON_KEY
const supabaseServiceRoleKey = import.meta.env.VITE_SUPABASE_SERVICE_ROLE_KEY

// Crear el cliente de Supabase
export const supabase = createClient(supabaseUrl, supabaseAnonKey)

// Cliente admin para operaciones de administración de usuarios
const supabaseAdmin = createClient(supabaseUrl, supabaseServiceRoleKey || supabaseAnonKey, {
  auth: { autoRefreshToken: false, persistSession: false, storageKey: 'supabase-admin' }
})

Provides helper functions:

getCurrentUser() - Get current authenticated user
getUserData() - Get user data with role from database
signOut() - Log out current user
getLocalDate() - Get local date in Venezuela timezone
createUserAccount() - Create new user (admin only)
changeUserPassword() - Update user password

supabase_schema.sql

Complete PostgreSQL database schema with:

Table definitions for all entities
Row Level Security (RLS) policies
Database triggers for automation
RPC functions for complex operations
Audit logging
Sample data

Key sections:

Tables: users, products, categories, guia_entrada, input, output, etc.
Triggers: Stock updates, audit logging, user protection
RPC Functions: aprobar_guia(), rechazar_guia(), procesar_operacion_diaria(), get_lotes_por_vencer()
RLS Policies: Role-based access control at database level
Views: Helpful views for common queries

package.json

Project metadata and dependencies:

{
  "name": "pae-inventory",
  "private": true,
  "version": "1.0.0",
  "type": "module",
  "description": "Sistema de Inventario del Programa de Alimentación Escolar",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview"
  },
  "dependencies": {
    "@supabase/supabase-js": "^2.39.0",
    "lucide-react": "^0.575.0",
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "react-router-dom": "^6.21.0",
    "sweetalert2": "^11.26.20"
  },
  "devDependencies": {
    "@vitejs/plugin-react": "^4.2.1",
    "autoprefixer": "^10.4.24",
    "postcss": "^8.5.6",
    "tailwindcss": "^3.4.19",
    "vite": "^5.0.8"
  }
}

Available Scripts

Development and build commands:

npm run dev

npm run dev
npm run build
npm run preview

Starts the Vite development server with:

Hot Module Replacement (HMR)
Fast refresh for React components
Source maps for debugging
Port 5173 by default

Perfect for local development.

Creates an optimized production build:

Minified JavaScript and CSS
Tree-shaking to remove unused code
Asset optimization
Output to dist/ folder

Deploy the dist/ folder to your hosting provider.

Preview the production build locally before deploying:

Serves the dist/ folder
Tests production build
Useful for final verification

Environment Variables Reference

All environment variables must be prefixed with VITE_ to be accessible in the frontend:

Variable	Required	Description
`VITE_SUPABASE_URL`	✅ Yes	Your Supabase project URL (e.g., `https://xxxxx.supabase.co`)
`VITE_SUPABASE_ANON_KEY`	✅ Yes	Supabase anonymous/public API key (safe for client-side)
`VITE_SUPABASE_SERVICE_ROLE_KEY`	⚠️ Recommended	Service role key for admin operations (user creation, password reset)

Never commit .env to version control! Add it to .gitignore:

# Environment variables
.env
.env.local
.env.production

Troubleshooting

Error: Faltan variables de entorno de Supabase

Problem: Missing or incorrectly named environment variables.Solution:

Verify .env file exists in project root
Check variable names start with VITE_
Restart the dev server after changing .env
Verify no typos in variable names

Database schema errors when running SQL

Problem: Schema already exists or syntax errors.Solution:

If updating: Tables may already exist (script uses IF NOT EXISTS)
Run in SQL Editor, not in migrations
Check PostgreSQL version compatibility (Supabase uses PostgreSQL 15)
Look for specific error messages in Supabase logs

RLS policy errors when accessing data

Problem: Row Level Security blocking access.Solution:

Verify user has correct id_rol in users table
Check RLS policies are enabled on all tables
Review policy definitions in schema
Test with Director role (has broadest access)

Port 5173 already in use

Problem: Another process is using the default Vite port.Solution:

# Use a different port
npm run dev -- --port 3000

Or kill the process using port 5173:

# Find the process
lsof -ti:5173
# Kill it
kill -9 $(lsof -ti:5173)

Deployment

When you’re ready to deploy to production:

Build for Production

npm run build

This creates optimized files in the dist/ directory.

Configure Production Environment

Set environment variables in your hosting platform (Vercel, Netlify, etc.):

VITE_SUPABASE_URL
VITE_SUPABASE_ANON_KEY
VITE_SUPABASE_SERVICE_ROLE_KEY

Deploy Static Files

Upload the dist/ folder to your hosting provider or use their CLI/Git integration.

Popular options: Vercel, Netlify, AWS Amplify, GitHub Pages (with GitHub Actions)

Configure Supabase for Production

Update Authentication → URL Configuration:
- Add your production domain to Site URL
- Add to Redirect URLs
Review RLS policies are enabled
Verify API keys are set correctly

In production, consider:

Using a custom domain with HTTPS
Setting up monitoring and error tracking
Configuring database backups in Supabase
Implementing rate limiting
Regular security audits

Next Steps

Quick Start Guide

Learn how to use the system

User Management

Create and manage user accounts

Database Schema

Deep dive into the database structure

Security

Understand security features and RLS policies

Development environment ready! Start building and testing features locally.

Get Started

Core Features

User Guides

Administration

Prerequisites

Node.js

npm

Git

Supabase Account Setup

Local Development Setup

Application Structure

Key Files Explained

Available Scripts

Environment Variables Reference

Troubleshooting

Deployment

Next Steps

Quick Start Guide

User Management

Database Schema

Security

Build docs developers (and LLMs) love

Get Started

Core Features

User Guides

Administration

​Prerequisites

Node.js

npm

Git

​Supabase Account Setup

​Local Development Setup

​Application Structure

​Key Files Explained

​Available Scripts

​Environment Variables Reference

​Troubleshooting

​Deployment

​Next Steps

Quick Start Guide

User Management

Database Schema

Security

Build docs developers (and LLMs) love

Prerequisites

Supabase Account Setup

Local Development Setup

Application Structure

Key Files Explained

Available Scripts

Environment Variables Reference

Troubleshooting

Deployment

Next Steps