Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ashcroft08/provesa-web/llms.txt

Use this file to discover all available pages before exploring further.

Complete guide to installing and configuring PROVESA Web, the institutional web platform and administrative panel for PROVESA SCC (Sociedad Cooperativa de Consumo).

​
System Requirements

​
Required Software

  • Node.js: Version 20 or higher
  • Package Manager: pnpm v9+ (recommended) or npm
  • Database: PostgreSQL 15 or higher (local or remote)

​
Optional Tools

  • Git: For cloning the repository
  • Database GUI: pgAdmin, TablePlus, or Drizzle Studio for database management

​
Installation Steps

1

Clone the repository

Clone the PROVESA Web repository from GitHub:
git clone https://github.com/ashcroft08/provesa-web.git
cd provesa-web
2

Install dependencies

Install all required dependencies using your preferred package manager:
npm install
This will install all dependencies listed in package.json, including:
  • SvelteKit 5 - Application framework
  • Drizzle ORM - Database toolkit
  • Better Auth - Authentication system
  • TailwindCSS 4 - Styling framework
  • Nodemailer - Email sending
  • Vitest & Playwright - Testing frameworks
3

Set up environment variables

Create your environment configuration file:
cp .env.example .env
Edit the .env file with your specific configuration:
.env
# Database Configuration
DATABASE_URL="postgres://user:password@host:5432/provesa"

# Application Origin
ORIGIN="http://localhost:5173"

# Authentication Secret (32 characters, high entropy)
BETTER_AUTH_SECRET=""

# Gmail Credentials for Password Recovery
GMAIL_USER="your-email@gmail.com"
GMAIL_APP_PASSWORD="your-app-password"

# Admin User Seed Configuration
ADMIN_NAME="Administrador"
ADMIN_EMAIL="admin@provesa.com"
ADMIN_PASSWORD="your-secure-password"
Never commit your .env file to version control. The .env.example file is provided as a template only.
4

Configure the database

Apply the database schema to your PostgreSQL database:
npm run db:push
This command uses Drizzle Kit to synchronize your database schema with the definitions in src/lib/server/db/schema.js.
5

Seed the database

Run the seed scripts to create initial data:
npm run db:seed
This will:
  • Create an admin user with the credentials from your .env file
  • Set up the default theme configuration
6

Start the development server

Launch the development server:
npm run dev
The application will be available at http://localhost:5173

​
Environment Variables Reference

​
Database Configuration

VariableDescriptionExample
DATABASE_URLPostgreSQL connection stringpostgres://user:password@localhost:5432/provesa
The database URL format is: postgres://username:password@host:port/database_name

​
Application Settings

VariableDescriptionExample
ORIGINBase URL of your applicationhttp://localhost:5173 (development)
https://provesa.com (production)

​
Authentication

VariableDescriptionRequired
BETTER_AUTH_SECRET32-character secret for session encryptionYes
Generate a cryptographically secure secret for production. You can use openssl rand -base64 32 or visit Better Auth documentation for recommendations.

​
Email Configuration

VariableDescriptionRequired
GMAIL_USERGmail address for sending emailsYes
GMAIL_APP_PASSWORDGmail app-specific passwordYes
To generate a Gmail App Password:
  1. Go to your Google Account settings
  2. Navigate to Security → 2-Step Verification
  3. Scroll to “App passwords”
  4. Generate a new app password for “Mail”
See Google’s guide for detailed instructions.

​
Admin User Seed

VariableDescriptionDefault
ADMIN_NAMEDisplay name for admin userAdministrador
ADMIN_EMAILAdmin login emailadmin@provesa.com
ADMIN_PASSWORDAdmin login password(required)

​
Available Scripts

PROVESA Web includes several npm scripts for different tasks:

​
Development

# Start development server
npm run dev

# Type-check the codebase
npm run check

# Type-check in watch mode
npm run check:watch

​
Database Management

# Push schema changes to database
npm run db:push

# Generate migrations
npm run db:generate

# Run migrations
npm run db:migrate

# Open Drizzle Studio (database GUI)
npm run db:studio

# Run seed scripts
npm run db:seed

​
Production Build

# Create production build
npm run build

# Preview production build locally
npm run preview

​
Testing & Quality

# Run all tests (unit + E2E)
npm test

# Run unit tests only
npm run test:unit

# Run E2E tests only
npm run test:e2e

# Lint code
npm run lint

# Format code with Prettier
npm run format

​
Project Structure

provesa-web/
├── drizzle/                      # Database migrations
├── src/
│   ├── lib/
│   │   ├── assets/               # Static resources (favicon, etc.)
│   │   ├── components/           # Reusable components (Navbar, Admin)
│   │   ├── server/
│   │   │   ├── auth.js           # Better Auth configuration
│   │   │   └── db/               # Drizzle schemas, seeds, connection
│   │   └── utils/                # Shared utilities
│   └── routes/
│       ├── admin/                # Admin panel (protected routes)
│       ├── login/                # Login page
│       ├── recuperar/            # Password recovery request
│       └── restablecer-password/ # Password reset
├── static/                       # Public static files
├── .env.example                  # Environment variables template
├── drizzle.config.js             # Drizzle Kit configuration
├── svelte.config.js              # SvelteKit configuration
└── vite.config.js                # Vite configuration

​
Technology Stack

PROVESA Web is built with modern web technologies:
TechnologyPurposeVersion
SvelteKitApplication framework5
SvelteUI framework with runes5
TailwindCSSUtility-first CSS framework4
PostgreSQLRelational database15+
Drizzle ORMTypeScript ORMLatest
Better AuthAuthentication libraryLatest
NodemailerEmail sending (Gmail)Latest
VitestUnit testing frameworkLatest
PlaywrightE2E testing frameworkLatest

​
Troubleshooting

​
Database Connection Issues

If you encounter database connection errors:
  1. Verify PostgreSQL is running: pg_isready
  2. Check your DATABASE_URL format is correct
  3. Ensure the database exists: createdb provesa
  4. Verify user permissions in PostgreSQL

​
Port Already in Use

If port 5173 is already in use: 
# Kill the process using port 5173
lsof -ti:5173 | xargs kill -9

# Or specify a different port
npm run dev -- --port 3000

​
Missing Environment Variables

If you see errors about missing environment variables:
  1. Ensure .env file exists in the project root
  2. Verify all required variables are set
  3. Restart the development server after changing .env

​
Gmail Authentication Errors

If password recovery emails fail to send:
  1. Verify GMAIL_USER and GMAIL_APP_PASSWORD are correct
  2. Ensure you’re using an App Password, not your regular Gmail password
  3. Check that 2-Step Verification is enabled on your Google account

​
Next Steps

After installation, you can:
  • Access the admin panel at /admin
  • Customize theme colors in the admin settings
  • Manage candidates and suggestions
  • Configure the public-facing website
  • Set up production deployment
For production deployment, ensure you’ve configured proper environment variables, enabled HTTPS, and followed security best practices for your database and authentication secrets.

Build docs developers (and LLMs) love

Get started for freeTalk to us