Skip to main content
GatePass uses a modern monolithic architecture with clear separation of concerns between Frontend, Backend API, and Blockchain interactions.

​
System Overview

GatePass is built as a monorepo with three main components that work together to deliver a seamless event ticketing experience:

​
Monorepo Structure

The GatePass codebase is organized as a monorepo with the following structure: 
gatepass/
├── src/
│   ├── packages/
│   │   ├── server/          # Backend API (Express + Node.js)
│   │   ├── contracts/       # Smart contracts (Solidity + Foundry)
│   │   └── database/        # Database schema (Prisma)
│   ├── components/          # React components
│   ├── services/            # Frontend services
│   ├── utils/               # Shared utilities
│   └── App.tsx             # Main application
├── public/                  # Static assets
├── package.json            # Root dependencies
└── vite.config.ts          # Vite configuration

​
Core Components

​
Frontend (React + Vite)

The frontend is built with modern React and provides a rich user experience for both attendees and organizers.

Technology Stack

  • React 18 with TypeScript
  • Vite for fast development
  • Tailwind CSS for styling
  • Shadcn UI components
  • Framer Motion for animations
  • React Query for data fetching
  • Zustand for state management

Key Features

  • Landing Page (src/components/LandingPage.tsx)
  • Authentication (src/components/LoginPage.tsx)
  • Organizer Dashboard (src/components/OrganizerDashboard.tsx)
  • Attendee Dashboard (src/components/AttendeeDashboard.tsx)
  • Event Creation (src/components/EventCreation.tsx)
  • Ticket Purchase (src/components/TicketPurchase.tsx)
  • Mobile Scanner (src/components/MobileScanner.tsx)
  • Analytics (src/components/Analytics.tsx)
Main Entry Point:
src/App.tsx
import { BrowserRouter } from 'react-router-dom'
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'

// Routes for different user flows
// - Landing page and event browsing
// - Authentication (Email, Google, Twitter, Web3)
// - Organizer dashboard (event management)
// - Attendee dashboard (ticket management)
// - Mobile scanner for check-ins

​
Backend API (Express + Node.js)

The backend API is built with Express.js and provides RESTful endpoints for all platform operations. Location: src/packages/server/
Main API Endpoints:
src/packages/server/src/index.ts:112-120
app.use('/api/health', healthRoutes)
app.use('/api/auth', authRoutes)
app.use('/api/events', eventRoutes)
app.use('/api/orders', orderRoutes)
app.use('/api/analytics', analyticsRoutes)
app.use('/api/notifications', notificationRoutes)
app.use('/api/webhooks', webhookRoutes)
  • Health: Server status and monitoring
  • Auth: User registration, login, OAuth
  • Events: CRUD operations for events
  • Orders: Ticket purchases and payments
  • Analytics: Sales and attendance metrics
  • Notifications: Real-time event updates
  • Webhooks: Payment gateway callbacks
src/packages/server/src/index.ts:36-73
// Security
app.use(helmet())                    // Security headers
app.use(compression())               // Response compression
app.use(cors({ /* config */ }))      // Cross-origin requests
app.use(limiter)                     // Rate limiting (100 req/15min)

// Body parsing
app.use(express.json({ limit: '10mb' }))
app.use(express.urlencoded({ extended: true }))

// Authentication
app.use(passport.initialize())
app.use(passport.session())

// Logging
app.use(morgan('combined'))

// Error handling
app.use(errorHandler)
Multiple authentication methods via Passport.js:
src/packages/server/src/config/passport.ts
import passport from 'passport'
import { Strategy as GoogleStrategy } from 'passport-google-oauth20'
import { Strategy as TwitterStrategy } from 'passport-twitter'

// Strategies:
// 1. Email/Password (JWT)
// 2. Google OAuth 2.0
// 3. Twitter OAuth
// 4. Web3 Wallet (MetaMask signature verification)
JWT Token Flow:
  • User logs in → Server generates JWT
  • Token stored in localStorage/cookies
  • Token sent in Authorization: Bearer <token> header
  • Middleware validates token on protected routes

​
Database (Prisma + PostgreSQL)

The database layer uses Prisma ORM for type-safe database access. Location: src/packages/database/
src/packages/database/schema.prisma
generator client {
  provider = "prisma-client-js"
  output   = "./generated/client"
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}
Core Models:

User Model

  • Email/password authentication
  • OAuth provider IDs (Google, Twitter)
  • Wallet address for Web3
  • Role-based access control
  • Refresh tokens

Event Model

  • Title, description, venue
  • Date and location (lat/long)
  • Ticket supply and pricing
  • Smart contract address
  • Sale start/end dates
  • Category and tags

Order Model

  • Payment method (fiat/crypto)
  • Payment status tracking
  • Gateway transaction IDs
  • Customer information
  • Related tickets

Ticket Model

  • ERC-721 token ID
  • Contract address
  • Blockchain transaction hash
  • Metadata URI
  • Usage status
  • Check-in tracking
Additional Models:
  • CheckIn - Event check-in records with POA NFT info
  • EventAnalytics - Sales and attendance metrics
  • TicketTier - Multiple pricing tiers per event
  • Notification - User notification system

​
Smart Contracts (Solidity + Foundry)

Blockchain smart contracts for NFT ticket management on Polygon. Location: src/packages/contracts/

EventTicket.sol

Main ERC-721 contract for event tickets

EventTicketFactory.sol

Factory for deploying new ticket contracts

ProofOfAttendance.sol

POA NFTs minted at check-in
src/packages/contracts/src/EventTicket.sol:16-57
contract EventTicket is ERC721, ERC721Enumerable, Ownable, ReentrancyGuard, Pausable {
    uint256 public totalSupply;        // Max tickets
    uint256 public ticketPrice;        // Price in wei
    uint256 public saleStart;          // Sale start timestamp
    uint256 public saleEnd;            // Sale end timestamp
    uint256 public eventDate;          // Event date
    uint256 public tokenCounter = 1;   // Minted count
    
    // Features:
    // - Public minting with ETH payment
    // - Allowlist minting (Merkle tree)
    // - Organizer minting (free tickets)
    // - Check-in system
    // - POA NFT minting on check-in
    // - Platform fee distribution
    // - Emergency pause
}
Key Functions:
  • mint(uint256 quantity) - Purchase tickets with ETH
  • allowListMint(...) - Allowlist presale
  • checkIn(uint256 tokenId) - Self check-in
  • organizerCheckIn(...) - Staff-assisted check-in
  • withdraw() - Organizer withdraws proceeds (after event)
src/packages/contracts/package.json:5-14
{
  "scripts": {
    "build": "forge build",
    "test": "forge test -vvv",
    "test:coverage": "forge coverage",
    "deploy:testnet": "forge script script/Deploy.s.sol --rpc-url $POLYGON_TESTNET_RPC",
    "deploy:mainnet": "forge script script/Deploy.s.sol --rpc-url $POLYGON_MAINNET_RPC",
    "verify": "forge verify-contract",
    "gas-report": "forge test --gas-report"
  }
}

​
Data Flow

​
Event Creation Flow

​
Ticket Purchase Flow

​
Check-in Flow

​
Technology Stack Summary

Frontend

  • React 18 + TypeScript
  • Vite 6.3.5
  • Tailwind CSS 3.4
  • Radix UI + Shadcn
  • Framer Motion 12
  • React Query
  • Ethers.js 6.16

Backend

  • Node.js 20+
  • Express 4.18
  • Prisma 5.7 ORM
  • PostgreSQL (prod) / SQLite (dev)
  • Passport.js
  • JWT Authentication
  • Winston Logger

Blockchain

  • Solidity ^0.8.24
  • OpenZeppelin Contracts
  • Foundry (Forge)
  • Polygon Mainnet
  • Ethers.js
  • IPFS for metadata

Payments

  • Paystack (Card, Bank)
  • Flutterwave (Mobile Money)
  • Stripe (International)
  • Coinbase Commerce (Crypto)
  • M-Pesa Integration

​
Security Features

  • JWT Authentication: Stateless token-based auth
  • Rate Limiting: 100 requests per 15 minutes per IP
  • Helmet.js: Security headers (CSP, XSS protection)
  • CORS: Whitelist-based origin validation
  • Input Validation: Joi/Express-validator on all inputs
  • SQL Injection Protection: Prisma parameterized queries
  • OpenZeppelin: Battle-tested contract libraries
  • ReentrancyGuard: Protection against reentrancy attacks
  • Pausable: Emergency stop mechanism
  • Access Control: Owner-only admin functions
  • Custom Errors: Gas-efficient error handling
  • Merkle Trees: Efficient allowlist verification
  • Webhook Verification: HMAC signature validation
  • Idempotency: Duplicate payment prevention
  • PCI Compliance: Never store card details
  • SSL/TLS: All API calls encrypted
  • Payment Processor Separation: Gateway handles sensitive data

​
Performance Optimizations

  • Frontend:
    • Code splitting with React.lazy()
    • Image optimization with sharp
    • React Query caching
    • Virtualized lists for large datasets
  • Backend:
    • Response compression (gzip)
    • Database connection pooling
    • Redis caching (optional)
    • Pagination for large result sets
  • Blockchain:
    • Batch minting for gas efficiency
    • Off-chain metadata storage (IPFS)
    • Optimized contract deployment (clones)
    • Event indexing for fast queries

​
Deployment Architecture

  • Frontend: Vite dev server (localhost:5173)
  • Backend: tsx watch (localhost:8000)
  • Database: SQLite local file
  • Blockchain: Polygon Mumbai testnet

​
Next Steps

API Reference

Explore the REST API endpoints

Smart Contracts

Learn about the NFT contracts

Development Guide

Contribute to the codebase

Contract Deployment

Deploy smart contracts to production

Build docs developers (and LLMs) love

Get started for freeTalk to us