Quickstart Guide

This guide will take you from zero to a fully functional Trazea installation with your first inventory item tracked.

Prerequisites

Before you begin, ensure you have:

Node.js 22 or higher installed
A Supabase account (free tier works fine)
pnpm package manager (recommended) or npm/yarn

Clone and Install

Clone the Trazea repository and install dependencies:

git clone <your-repository-url>
cd trazea
pnpm install

Installation typically takes 2-3 minutes depending on your internet connection.

Configure Environment Variables

Copy the example environment file and configure your credentials:

cp .env.example .env

Open .env and add your Supabase credentials:

.env

# Supabase Configuration (Required)
VITE_SUPABASE_URL=https://your-project.supabase.co
VITE_SUPABASE_ANON_KEY=your-anon-key-here

# Sentry Configuration (Optional)
VITE_SENTRY_DSN=https://[email protected]/project-id

# ElevenLabs Configuration (Optional - for voice features)
VITE_PUBLIC_ELEVENLABS_API_KEY=your-elevenlabs-key

The VITE_SUPABASE_URL and VITE_SUPABASE_ANON_KEY are required. You can find these in your Supabase project settings under Settings → API.

Getting Supabase Credentials

Go to supabase.com and sign in
Create a new project or select an existing one
Navigate to Settings → API
Copy the Project URL to VITE_SUPABASE_URL
Copy the anon public key to VITE_SUPABASE_ANON_KEY

Start Development Server

Launch the application in development mode:

pnpm dev

The app will be available at http://localhost:5173

The development server includes hot module replacement (HMR) for instant updates as you make changes.

Create Your Account

Navigate to http://localhost:5173 in your browser. You’ll see the login page. Trazea login screen

Since this is your first time, you’ll need to create an account:

Click the registration link (if available) or use Google OAuth
Enter your email and create a password
Submit the registration form

New user accounts require admin approval by default. You’ll see a “Pending Approval” message after registration.

Approving Your First User

To approve your account, you’ll need to update the database directly:

-- In Supabase SQL Editor
UPDATE usuarios 
SET aprobado = true, 
    aprobado_por = id_usuario,
    fecha_aprobacion = NOW()
WHERE email = '[email protected]';

Alternatively, you can log in with Google OAuth:

// The login form supports Google authentication
const { loginWithGoogle } = useLogin();
await loginWithGoogle();

Configure Your First Location

After logging in, set up your first warehouse location:

Navigate to Settings → Locations
Click Add New Location
Fill in the location details:

{
  nombre: "Main Warehouse",
  telefono: "+1-555-0123"
}

Locations in Trazea represent physical warehouses or stores where inventory is kept. Each location maintains independent stock levels.

You can create multiple locations and transfer inventory between them using the request system.

Add Your First Spare Part

Now let’s add a spare part to the catalog:

Go to Catalog → Spare Parts
Click Create New Part
Fill in the part details:

{
  referencia: "MTR-001",
  nombre: "Electric Motor 48V",
  tipo: "Motor",
  marca: "MINCA",
  descripcion: "High-performance 48V electric motor",
  descontinuado: false
}

Available Part Types

General - Miscellaneous parts
Motor - Engine and motor components
Transmision - Transmission parts
Frenos - Brake systems
Suspension - Suspension components
Electrico - Electrical systems
Carrocería - Body parts

The referencia field is the unique identifier for each part. Make it descriptive and consistent.

Create Your First Inventory Item

Finally, add this part to your location’s inventory:

Navigate to Inventory → [Your Location]
Click Add to Inventory
Select the spare part you just created
Configure the inventory details:

{
  stock_actual: 10,
  cantidad_minima: 2,
  posicion: "A1-B3",  // Physical location in warehouse
  estado_stock: "NORMAL"  // Auto-calculated based on stock levels
}

Inventory Fields Explained

stock_actual - Current quantity in warehouse
cantidad_minima - Minimum stock level before alerts
posicion - Physical location code in your warehouse
estado_stock - Automatically calculated:
- NORMAL - Stock above minimum
- BAJO - Stock at or near minimum
- CRITICO - Stock below minimum or zero

When stock falls below cantidad_minima, the system automatically generates low stock notifications.

Verify Everything Works

Let’s confirm your setup:

Go to Inventory → [Your Location]
You should see your inventory item with:
- Green stock badge (NORMAL status)
- Stock count of 10
- The “NEW” badge (items are marked as new for 5 days)
Click on the item to open the edit sheet
Try updating the stock quantity:

// This action creates an audit log entry
stock_actual: 8  // Decrease by 2

Check Records → Inventory Logs to see the logged change

Audit Trail

Every inventory change is automatically logged with:

User who made the change
Previous quantity
New quantity
Timestamp
Operation type (manual adjustment, request fulfillment, etc.)

Next Steps

Request Parts Between Locations

Set up your workflow for transferring parts between warehouses with full traceability

Configure User Roles

Set up role-based access control with granular permissions

Set Up Warranties

Enable warranty tracking with photo evidence and status workflows

Physical Counts

Learn how to perform inventory audits and reconcile discrepancies

Common First-Time Issues

Can't log in after registration

New accounts require admin approval. Check the usuarios table in Supabase and set aprobado = true for your account.

UPDATE usuarios 
SET aprobado = true 
WHERE email = '[email protected]';

Environment variables not loading

Make sure your .env file is in the project root (same directory as package.json). Variable names must start with VITE_ to be exposed to the frontend.Restart the development server after changing environment variables:

pnpm dev

Database connection errors

Verify your Supabase credentials:

Check that VITE_SUPABASE_URL uses https:// protocol
Ensure VITE_SUPABASE_ANON_KEY is the anon key, not the service_role key
Confirm your Supabase project is active and not paused

Parts not appearing in inventory

Spare parts and inventory items are separate entities:

First create the spare part in the catalog
Then add it to inventory for a specific location

Think of spare parts as the master catalog, and inventory items as location-specific instances.

Quick Reference: Key Concepts

Concept	Description	Example
Repuesto	Master catalog of all spare parts	”Electric Motor 48V”
Inventario	Location-specific stock of a repuesto	10 motors at Main Warehouse
Localizacion	Physical warehouse or store	”Main Warehouse”, “Branch Store”
Solicitud	Request to transfer parts between locations	Transfer 5 motors from Main to Branch
Movimiento	Technician’s daily part usage record	Loaded 2 motors for repair order #123
Garantía	Warranty claim for defective parts	Motor failed at 500km

Development Workflow

Now that you’re set up, here’s a typical development workflow:

# Start development server
pnpm dev

# Run linting
pnpm lint

# Build for production
pnpm build

# Preview production build
pnpm preview

The project uses Vite for blazing-fast HMR and optimized production builds. Changes to React components will hot-reload instantly.

Architecture Overview

Trazea uses Feature-Sliced Design (FSD) for maintainable, scalable architecture:

src/
├── app/          → Global config, routing, providers
├── pages/        → Route-level components
├── widgets/      → Composite UI components
├── features/     → User-facing features
├── entities/     → Business domain models
└── shared/       → Reusable utilities and UI

Each feature is self-contained with its own:

UI components (ui/)
Business logic (lib/)
Type definitions (model/)
API calls (api/)

Learn More About FSD

Explore the Feature-Sliced Design methodology for scalable frontend architecture

Get Started

Core Features

Architecture

Guides

Deployment

Quickstart Guide

Prerequisites

Getting Supabase Credentials

Approving Your First User

Available Part Types

Inventory Fields Explained

Audit Trail

Next Steps

Request Parts Between Locations

Configure User Roles

Set Up Warranties

Physical Counts

Common First-Time Issues

Quick Reference: Key Concepts

Development Workflow

Architecture Overview

Learn More About FSD

Build docs developers (and LLMs) love

Get Started

Core Features

Architecture

Guides

Deployment

​Prerequisites

​Getting Supabase Credentials

​Approving Your First User

​Available Part Types

​Inventory Fields Explained

​Audit Trail

​Next Steps

Request Parts Between Locations

Configure User Roles

Set Up Warranties

Physical Counts

​Common First-Time Issues

​Quick Reference: Key Concepts

​Development Workflow

​Architecture Overview

Learn More About FSD

Build docs developers (and LLMs) love

Prerequisites

Getting Supabase Credentials

Approving Your First User

Available Part Types

Inventory Fields Explained

Audit Trail

Next Steps

Common First-Time Issues

Quick Reference: Key Concepts

Development Workflow

Architecture Overview