Skip to main content
GatePass is a decentralized event ticketing platform that uses blockchain technology (NFTs) for secure, verifiable tickets. This guide will help you set up your local development environment.

​
Prerequisites

Before you begin, ensure you have the following installed:

Node.js

Version 18 or higher required

npm or pnpm

Package manager for dependencies

Git

Version control system

PostgreSQL

Optional: SQLite used by default for development

​
Quick Start

​
1. Clone the Repository

git clone https://github.com/yourusername/gatepass.git
cd gatepass

​
2. Install Dependencies

Install all project dependencies using npm: 
npm install
This will install dependencies for:
  • Frontend (React/Vite)
  • Backend API (Express/Node.js)
  • Database package (Prisma)
The project uses a monorepo structure with packages in src/packages/

​
3. Environment Configuration

Copy the example environment file and configure your variables: 
# Root environment file (frontend)
cp .env.example .env
Edit .env and add your configuration. See Environment Variables for detailed information. Required variables for basic setup:
.env
# Payment gateways (optional for testing)
VITE_PAYSTACK_PUBLIC_KEY=pk_test_your_paystack_key
VITE_FLUTTERWAVE_PUBLIC_KEY=FLWPUBK_TEST-your_flutterwave_key

# Blockchain configuration
VITE_CHAIN_ID=137
VITE_RPC_URL=https://polygon-rpc.com

​
4. Database Setup

The project uses Prisma ORM with SQLite for development and PostgreSQL for production.

​
Initialize the Database

Navigate to the database package and run migrations: 
cd src/packages/database
npx prisma migrate dev
This command will:
  • Create the SQLite database file (dev.db)
  • Run all migrations
  • Generate the Prisma Client

​
Seed Demo Data

Populate the database with sample events and users: 
cd src/packages/server
npx tsx src/scripts/seedEvents.ts
Seed data includes sample events, users, and tickets for testing the application.

​
5. Run the Application

The application consists of two main parts that need to be running:

​
Start the Backend Server

Open a terminal window and start the Express API server: 
cd src/packages/server
npm run dev
The backend will start on port 8000.

​
Start the Frontend Development Server

Open a new terminal window and start the Vite development server: 
# From the root directory
npm run dev
The frontend will start on port 5173.
Success! Your development environment is now running.

​
Access the Application

Frontend

Main application interfacehttp://localhost:5173

Backend API

REST API serverhttp://localhost:8000

API Documentation

Swagger API docshttp://localhost:8000/docs

Prisma Studio

Database GUI (run npm run studio)http://localhost:5555

​
Development Workflow

​
Making Code Changes

Both the frontend and backend support hot module replacement (HMR):
  • Frontend: Vite automatically reloads changes in .tsx, .ts, and .css files
  • Backend: tsx watch mode automatically restarts the server on file changes

​
Database Changes

When you modify the Prisma schema: 
cd src/packages/database

# Create a new migration
npx prisma migrate dev --name your_migration_name

# Regenerate Prisma Client
npx prisma generate

​
View Database

Use Prisma Studio to view and edit your database: 
cd src/packages/database
npx prisma studio
This opens a GUI at http://localhost:5555.

​
Project Structure

gatepass/
├── src/
│   ├── components/        # React components
│   ├── pages/             # Page components
│   ├── services/          # API service layer
│   ├── utils/             # Utility functions
│   ├── packages/
│   │   ├── server/        # Backend API (Express)
│   │   │   ├── src/
│   │   │   │   ├── routes/
│   │   │   │   ├── controllers/
│   │   │   │   ├── middleware/
│   │   │   │   └── scripts/
│   │   │   └── package.json
│   │   └── database/      # Prisma schema and client
│   │       ├── schema.prisma
│   │       └── package.json
│   └── ...
├── public/                # Static assets
├── .env.example           # Environment template
├── package.json           # Root dependencies
└── vite.config.ts         # Vite configuration

​
Common Commands

npm run dev          # Start development server (port 5173)
npm run build        # Build for production
npm run test         # Run tests with Vitest

cd src/packages/server
npm run dev          # Start with hot reload (port 8000)
npm run build        # Compile TypeScript
npm start            # Run production build
npm test             # Run Jest tests
npm run lint         # Run ESLint

cd src/packages/database
npm run generate     # Generate Prisma Client
npm run migrate      # Run migrations
npm run push         # Push schema to database
npm run studio       # Open Prisma Studio
npm run seed         # Seed database
npm run reset        # Reset database

​
Troubleshooting

If you see an error about ports 5173 or 8000 being in use:
# Find and kill the process on port 5173 (frontend)
lsof -ti:5173 | xargs kill -9

# Find and kill the process on port 8000 (backend)
lsof -ti:8000 | xargs kill -9
If you encounter database errors:
cd src/packages/database

# Reset the database and run migrations
npx prisma migrate reset

# Regenerate Prisma Client
npx prisma generate
If you see module resolution errors:
# Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

# Also clean package directories
rm -rf src/packages/*/node_modules
cd src/packages/database && npm install
cd ../server && npm install
If Prisma Client is not found:
cd src/packages/database
npx prisma generate
The Prisma Client is generated to src/packages/database/generated/client.

​
Next Steps

Environment Variables

Configure your development environment

Database Schema

Learn about the data models

Testing

Run and write tests

API Reference

Explore API endpoints
Security Note: Never commit your .env file to version control. Always use .env.example as a template.

Build docs developers (and LLMs) love

Get started for freeTalk to us