Quickstart

Overview

ICL Cotizaciones is a freight quotation management SaaS application built with Next.js. This guide will walk you through setting up the application locally and creating your first quotation.

This quickstart focuses on local development. The application uses SQLite for the database, making setup straightforward with no external dependencies.

Prerequisites

Before you begin, ensure you have:

Node.js 18 or higher installed
npm or yarn package manager
A terminal application
Git (for cloning the repository)

Setup Steps

Clone the repository

Clone the ICL Cotizaciones repository to your local machine:

git clone <repository-url>
cd iclapp

Replace <repository-url> with your actual repository URL.

Install dependencies

Install all required npm packages:

npm install

The application uses:

Next.js 16 with App Router
Drizzle ORM for database operations
iron-session for authentication
Radix UI and Tailwind CSS for the interface

Initialize the database

Generate the database schema and seed it with sample data:

npm run db:generate
npm run db:seed

This creates:

SQLite database at data/icl.db
8 test users (admin + commercial team)
30 sample clients
20 origin locations (China, India, Vietnam, etc.)
20 via locations (Buenos Aires, Miami, Hamburg, etc.)
200 sample quotations with realistic data

The seed script deletes any existing database. Only run db:seed when you want a fresh start.

Start the development server

Launch the Next.js development server:

npm run dev

The application will start on http://localhost:3000

Next.js uses Turbopack for faster development builds.

Navigate to http://localhost:3000 in your browser. You’ll be automatically redirected to the login page.

Test Credentials

The seed data includes several test users. Use any of these credentials to log in:

Admin User

Email: [email protected]
Password: icl2026
Role: DIRECTOR (full access)

Commercial User

Email: [email protected]
Password: icl2026
Role: COMERCIAL (sales role)

All seeded users use the same password: icl2026Available test accounts include:

[email protected] (DIRECTOR)
[email protected] (COMERCIAL)
[email protected] (COMERCIAL)
[email protected] (COMERCIAL)
[email protected] (COMERCIAL)
[email protected] (COMERCIAL)
[email protected] (COMERCIAL)
[email protected] (GERENTE)

Enter credentials

On the login page (/login):

Enter email: [email protected]
Enter password: icl2026
Click Ingresar

Authentication

The application:

Validates credentials via /api/auth/login
Hashes and compares passwords using bcryptjs
Creates an encrypted session using iron-session
Sets a secure HTTP-only cookie

Redirect to dashboard

Upon successful login, you’re redirected to /cotizaciones — the main quotations dashboard.

Navigate the Dashboard

The quotations dashboard (/cotizaciones) is your main workspace:

Dashboard Features

┌─────────────────────────────────────────────┐
│ [ICL Logo]  [Dashboard] [Clientes] [...]   │ ← Navigation
├─────────────────────────────────────────────┤
│ 200 cotizaciones                            │ ← Total count
├─────────────────────────────────────────────┤
│ Filters:                                     │
│ [Desde] [Hasta] [Estado] [Cliente] [...]   │ ← Filter controls
│            [Limpiar] [Nueva Cotización]     │
├─────────────────────────────────────────────┤
│ Semana 2026-S10 (15 cotizaciones)          │ ← Grouped by week
│ ┌───────────────────────────────────────┐  │
│ │ COT-2603-0001  Cliente X  Shanghai... │  │ ← Quotation rows
│ │ COT-2603-0002  Cliente Y  Mumbai...   │  │
│ └───────────────────────────────────────┘  │
└─────────────────────────────────────────────┘

Available Filters

Date range: Filter by creation date
Estado (Status): Ganada (Won), Perdida (Lost), Pendiente (Pending), En cotización
Cliente (Client): Filter by FFWW client
Via: Filter by destination port
Comercial: Filter by sales representative (admin only)
Search: Free text search across all fields

Commercial users see only their own quotations by default. Admin roles (DIRECTOR, GERENTE, ADMINISTRACION) see all quotations.

Create Your First Quotation

Click 'Nueva Cotización'

From the dashboard, click the blue Nueva Cotización button in the top-right filters section.You’ll be taken to /cotizaciones/nueva — the quotation creation form.

Fill in quotation details

The form is organized into several sections:

1. Operation Details

Impo/Expo: IMPO (import) or EXPO (export)
Tipo: GENERAL, PELIGROSA, REFRIGERADA, SOBREDIMENSIONADA
FCL/LCL: Container type (Full Container Load or Less than Container Load)
Condición de Venta: FOB, EXW, CIF, CFR, DDP

2. Client & Route

Cliente FFWW: Select from existing clients (or create new)
Cliente Final: Optional end client name
Origen: Port of origin (Shanghai, Mumbai, etc.)
Vía: Destination port (Buenos Aires, Miami, etc.)
Pick Up Address: Optional pickup location

3. Cargo Information

KGS: Weight in kilograms
CBM Reales: Actual cubic meters
CBM Facturables: Billable cubic meters
Detalle de la Carga: Cargo description
Apilable: SI/NO (stackable)
IMO: Hazardous material class (if applicable)

4. Cost Structure

Moneda: USD, EUR, or ARS
Flete Neto: Net freight cost
Flete Venta: Freight sale price
Gastos Origen Neto: Net origin costs
Gastos Origen Venta: Origin costs sale price
Profit: Automatically calculated

5. Additional Information

Referencia: Internal reference
Observaciones: Notes
Validez de Tarifa: Rate validity date

{
  impo_expo: "IMPO",
  tipo: "GENERAL",
  load_type: "LCL",
  sale_condition: "FOB",
  client_id: 1, // "Aceros Zapla SA"
  origin_id: 1, // "Shanghai, China"
  via_id: 21,   // "Buenos Aires, Argentina"
  kgs: 5000,
  billable_cbm: 15.5,
  actual_cbm: 14.2,
  description: "Repuestos automotor",
  currency: "USD",
  freight_net: 1200,
  freight_sale: 1500,
  origin_costs_net: 150,
  origin_costs_sale: 200
}

Save the quotation

Click Guardar at the bottom of the form.The application will:

Generate a unique quotation number (e.g., COT-2603-0001)
Calculate profit automatically
Set status to ENCOTIZACION (In Quotation)
Save via POST /api/cotizaciones
Redirect you to the quotation detail page

View your quotation

You’ll be taken to /cotizaciones/{id} where you can:

Edit the quotation
Change status (Ganada, Perdida, Pendiente)
Preview email and export to PDF
Duplicate to create similar quotations
Delete if needed (soft delete)

Database Schema Overview

Understanding the core tables helps you work with the application:

users

User accounts with roles:

DIRECTOR
GERENTE
COMERCIAL
CSV
OPERACIONES
ADMINISTRACION

clients

Client companies with:

Legal name & tax ID
Client type (FFWW, Final, Both)
Assigned sales representative

quotations

Main quotation entity:

Quote number, date, time
Operation type, route, cargo
Cost structure & profit
Status tracking

locations

Origin and via ports:

Name, country, region
Type: origen or via

For complete schema details, see Database Schema.

Next Steps

Now that you have ICL Cotizaciones running:

Explore Features

Learn about client management, commercial agreements, and analytics

API Reference

Explore all available API endpoints

User Roles

Understand permission levels and access control

Deployment

Deploy to production with environment configuration

Troubleshooting

Database file not found

If you get a database error, ensure you’ve run:

npm run db:generate
npm run db:seed

The database file should exist at data/icl.db.

Port 3000 already in use

If port 3000 is occupied, you can:

# Use a different port
PORT=3001 npm run dev

Or kill the process using port 3000.

Need to reset database

To start fresh with seed data:

npm run db:seed

This deletes the existing database and creates a new one with sample data.

Additional Resources

Source Code

View the complete source code structure and implementation

Architecture

Understand the application architecture and design patterns

Get Started

Architecture

Core Features

User Guides

Operations

Overview

Prerequisites

Setup Steps

Test Credentials

Admin User

Commercial User

Navigate the Dashboard

Dashboard Features

Available Filters

Create Your First Quotation

1. Operation Details

2. Client & Route

3. Cargo Information

4. Cost Structure

5. Additional Information

Database Schema Overview

users

clients

quotations

locations

Next Steps

Explore Features

API Reference

User Roles

Deployment

Troubleshooting

Additional Resources

Source Code

Architecture

Build docs developers (and LLMs) love

Get Started

Architecture

Core Features

User Guides

Operations

​Overview

​Prerequisites

​Setup Steps

​First Login

​Test Credentials

Admin User

Commercial User

​Login Flow

​Navigate the Dashboard

​Dashboard Features

​Available Filters

​Create Your First Quotation

​1. Operation Details

​2. Client & Route

​3. Cargo Information

​4. Cost Structure

​5. Additional Information

​Database Schema Overview

users

clients

quotations

locations

​Next Steps

Explore Features

API Reference

User Roles

Deployment

​Troubleshooting

​Additional Resources

Source Code

Architecture

Build docs developers (and LLMs) love

Overview

Prerequisites

Setup Steps

First Login

Test Credentials

Login Flow

Navigate the Dashboard

Dashboard Features

Available Filters

Create Your First Quotation

1. Operation Details

2. Client & Route

3. Cargo Information

4. Cost Structure

5. Additional Information

Database Schema Overview

Next Steps

Troubleshooting

Additional Resources