The Only Tip Management Platform with Built-In Compliance by Vincent PasiliThe Only Tip Management Platform with Built-In Compliance by Vincent Pasili

The Only Tip Management Platform with Built-In Compliance

Vincent Pasili

Verified

Completed work

Software Architect

Software Engineer

Software Consultant

ExpressJS

PostgreSQL

Vite

Food & Beverage

ProTip - Automated Tip Distribution & Payroll Compliance Platform

Overview

ProTip is a comprehensive full-stack web application designed specifically for restaurants and hospitality businesses to modernize their tip management and employee operations. The platform transforms traditional spreadsheet-based tip tracking into a real-time analytics dashboard with automated calculations, multi-model tip distribution, and jurisdiction-aware payroll compliance. Built for both business owners and employees, ProTip provides complete transparency in tip distribution while automating the complex regulatory math that restaurants currently do by hand — with penny-exact precision that matches the Excel spreadsheets it replaces.

Key Features

🏢 For Business Owners

Three Tip Distribution Models: Pooling (weighted hours), sharing (tip-out percentages), and hybrid (multi-pool with priority-ordered routing between revenue centers) — configurable per business

Automated Payroll Compliance: NY Department of Labor-compliant overtime with blended rate calculations, spread-of-hours detection for 10+ hour workdays, and automatic minimum wage make-up

Interactive Shift Calendar: Visual calendar interface for daily shift logging with clock-in/out times, role assignments, break tracking, and real-time tip calculations as data is entered

Tip Sheet Approval Workflow: State machine workflow (Draft → Submitted → Approved/Rejected) with optimistic concurrency control preventing two managers from overwriting each other's edits

Guided Business Onboarding: Three-step wizard with address autocomplete to auto-detect jurisdiction-specific labor rules, role configuration with point values, and wage rate setup

Revenue Center Management: Organize operations by different areas (bar, dining room, private events, takeout) with independent tip distribution rules per center

Payroll Export: Weekly payroll summaries with overtime, spread pay, minimum wage make-up, and processing fee deductions — exportable as Excel and PDF

CSV Bulk Import: Import employees, roles, and shift data from existing spreadsheets with intelligent duplicate detection

👤 For Employees

Personal Workspace Portal: Dedicated dashboard showing every shift, every tip breakdown, and every calculation with full transparency into how compensation was computed

Multi-Workspace Support: Employees who work at multiple restaurants switch between independent workspaces in a dropdown, each with its own permissions, wage rates, and role assignments

Private Tip Journal: Personal tracking tool to compare actual received tips against employer records

Real-Time Notifications: Email alerts for shift assignments, approval decisions, permission changes, and workspace invitations via Brevo transactional email

Mobile-Responsive Design: Card-based layouts optimized for phones where employees actually check their tips during breaks

💰 Tip Calculation Engine

Weighted Hour Distribution: Fair tip allocation based on hours worked multiplied by role points (0–2 range), with higher-point roles earning proportionally more per hour

Excel-Compatible Precision: Round-half-up rounding applied at every aggregation boundary (shift, daily, weekly, payroll) to match exactly how managers calculate in spreadsheets

Processing Fee Management: Automatic credit card fee deduction with configurable percentages, applied after adjustments and rounded independently before distribution

Custom Tip Fields: Support for additional income sources (online tips, delivery, service charges) with configurable processing fee application per field

Miscellaneous Adjustments: Manual adjustment support applied before fee calculation, matching the order of operations managers expect from Excel

📊 Payroll & Compliance

NY DOL Overtime Calculation: Four-step overtime formula for tipped employees using blended weighted rates, tip credit derivation, minimum overtime rate thresholds, and premium-above-regular-rate calculation

Spread of Hours Detection: Automatic detection of workdays spanning 10+ hours (earliest clock-in to latest clock-out), handling overnight shifts that cross midnight and multiple shifts in one day

Regional Minimum Wage Resolution: Hierarchical jurisdiction codes with temporal validity ranges — NYC, Long Island, and Westchester rates resolve automatically based on business address

Minimum Wage Make-Up: Automatic compliance check ensuring tipped employees' total compensation (wages + tips + overtime) meets minimum wage, with spread pay correctly excluded from the check but included in total earnings

Historical Rate Resolution: Temporal data pattern tracking pay rate changes by employee, role, and effective date range — payroll always uses the rate in effect on the specific shift date, not the current rate

Configurable Payroll Periods: Weekly, bi-weekly, semi-monthly, and monthly payroll cycles with configurable week start day

🔒 Authentication & Security

Flexible Login: Support for both username and email authentication with automatic format detection

Zero-Downtime Password Migration: Dual hash support (bcrypt for new, scrypt for legacy) enabling live migration without forcing password resets

Secure Invitation Flow: Temporary password system with TEMP_ prefix detection, forced password reset on first login, and session regeneration to prevent fixation attacks

Session-Based Security: Passport.js with PostgreSQL-backed session store, HTTP-only cookies, and 30-day TTL

Role-Based Access Control: Three-tier permission hierarchy (Portal Access → EDITOR → MANAGER) with cascading revocation — revoking EDITOR automatically revokes MANAGER

Multi-Tenant Data Isolation: Every database query (40+ methods) filters by company identifier with no unscoped API endpoints

Technology Stack

Frontend

React 18 with TypeScript for type-safe component development

Vite for fast development server with hot module replacement and optimized production builds

Wouter for lightweight client-side routing across 50+ routes with minimal bundle impact

TanStack Query for server state management with five-minute stale time, eliminating need for Redux or Zustand

shadcn/ui with Radix UI primitives for accessible, themeable component library

TailwindCSS for utility-first responsive design system

Framer Motion for smooth animations and page transitions

React Hook Form with Zod validation — same schemas used on server for guaranteed client-server sync

Recharts for data visualization (bar, line, and pie charts for tip analytics and performance trends)

date-fns for date manipulation across time zones and payroll period calculations

Backend

Node.js with Express.js REST API organized into 18 domain-specific route modules

TypeScript end-to-end with shared types between client and server via monorepo architecture

Passport.js for session-based authentication with PostgreSQL store via connect-pg-simple

bcrypt.js for secure password hashing with dual format support (bcrypt + legacy scrypt)

Multer for file upload handling (CSV imports, tip sheet attachments)

Brevo (Sendinblue) for transactional email delivery (invitations, shift notifications, password resets)

Database & ORM

PostgreSQL with Neon serverless hosting for robust multi-tenant data persistence

Drizzle ORM for type-safe database operations with SQL-like query builder providing fine control over complex aggregation queries

Drizzle Kit for schema migrations and database push operations

Zod for runtime validation with schemas derived directly from database column definitions via createInsertSchema

30+ tables with composite primary keys, unique constraints enforcing business rules, JSON columns for flexible configuration, and compound indexes optimized for temporal queries

External Services & APIs

Google Places API for address autocomplete during business onboarding and automatic jurisdiction detection

Brevo for email delivery — invitation emails, shift completion summaries, approval notifications, and password resets

Neon for serverless PostgreSQL with automatic backups and connection pooling

Development & Deployment

Replit for cloud-based development environment with automatic deployment

esbuild for production backend bundling

PostCSS with Autoprefixer for CSS processing

Automatic HTTPS with Let's Encrypt SSL/TLS certificates

CI/CD with automatic deployments on git push

Architecture Highlights

Database Design

Multi-tenant architecture with strict company ID isolation across all 30+ tables

Many-to-many employee-company relationships via junction table with composite primary keys, enabling employees to work at multiple restaurants with independent permissions, wages, and roles per workspace

Temporal data pattern for rate history — pay rate changes tracked with effective date ranges and compound indexes for efficient historical lookups

Regulatory jurisdictions table with hierarchical codes and temporal validity for automatic minimum wage resolution

Soft delete pattern with isActive flags preserving historical data for payroll auditability

Shift approval state machine (Draft → Submitted → Approved/Rejected) with version field for optimistic concurrency control and active editor tracking for conflict prevention

Calculation Architecture

Shared formula module between client and server ensuring identical calculations in browser previews and final server computation

Four-level aggregation hierarchy: shift → daily → weekly → payroll period, with rounding applied at each boundary to match Excel behavior

Policy-driven calculation engine — company settings (break deduction, processing fee application, spread of hours, overtime) toggle calculation paths without code changes

Compliance layering with correct inclusion/exclusion rules: spread pay excluded from minimum wage check but included in total compensation

Authentication System

Hybrid password verification supporting three formats simultaneously: bcrypt (new), scrypt (legacy), and temporary invitation passwords

Organic migration strategy — new passwords always use bcrypt while legacy hashes continue working indefinitely

Session regeneration on temporary password login to prevent session fixation attacks from invitation links

Dual-lookup login accepting both username and email by detecting @ character in input

Multi-Tenant Security

Company ID filtering enforced at the database query layer across 40+ storage methods

Workspace context header validation for employees accessing multiple companies

Cascading permission hierarchy preventing orphaned permission states

Invitation system with automatic account deduplication — existing users get company associations, not duplicate accounts

Inspiration & Similar Platforms

This project draws inspiration from leading platforms in the restaurant management and payroll space:

Square for Restaurants — Clean POS interface and employee management with data-forward design language

Toast POS — Comprehensive restaurant management workflows and the industry standard for full-service restaurants

7shifts — Restaurant-specific scheduling and labor management with a vertical focus that validated building domain-specific over general-purpose

Gusto — Payroll processing and employee self-service portals that inspired ProTip's employee workspace transparency

When I Work — Shift scheduling and time tracking with calendar-driven UX that influenced ProTip's shift management interface

Homebase — Small business team management combining scheduling, time tracking, and payroll

TipHaus — Tip pooling and distribution automation specifically for the restaurant industry

Kickfin — Digital tip distribution with instant cashless payouts to employee bank accounts

Design Approach

Design Tools & Resources

Figma — Primary design tool for mockups and prototyping multi-step workflows

shadcn/ui — Modern component library with Radix UI primitives for accessible, unstyled components

Tailwind UI — Professional component patterns and layout structures for rapid iteration

Lucide Icons — Comprehensive icon set with clean line style matching the professional aesthetic

Recharts — Data visualization library for analytics dashboard charts

Design Principles

Mobile-First: Every interface optimized for phones where restaurant staff actually check their tips during breaks

Progressive Disclosure: Complex features (payroll settings, hybrid tip models) revealed gradually to avoid overwhelming new users

Data-Dense Tables: Excel-like table layouts for power users who need quick data access, inspired by the spreadsheets the platform replaces

Smart Defaults: Pre-configured templates for common restaurant roles (server, bartender, busser, food runner) so setup isn't overwhelming

No Stock Photos: Cleaner professional interface focused on data and functionality

Contextual Help: Inline tooltips and help text rather than separate documentation pages

Project Structure

├── client/                  # React frontend application
│   ├── src/
│   │   ├── components/      # Reusable UI components
│   │   │   ├── ui/          # shadcn/ui component library
│   │   │   ├── layout/      # App shell, navigation, sidebars
│   │   │   └── tip-tracking/ # Tip entry and distribution components
│   │   ├── pages/           # 50+ page components and routes
│   │   ├── hooks/           # Custom React hooks (auth, queries)
│   │   └── lib/             # Utilities, tip calculations, config
├── server/                  # Express.js backend API
│   ├── routes/              # 18 domain-specific route modules
│   ├── scripts/             # Database seed scripts
│   └── index.ts             # Server entry point with error handling
├── shared/                  # Shared code between client and server
│   ├── schema.ts            # Drizzle ORM schema (single source of truth)
│   └── formulas/            # Tip distribution and payroll formulas
└── docs/                    # Project documentation

Learning Outcomes

This project demonstrates proficiency in:

Full-stack TypeScript development with shared types across client and server

Complex business logic implementation (weighted tip distribution, regulatory payroll compliance)

Multi-tenant SaaS architecture with strict data isolation

Temporal data patterns for historical rate tracking and regulatory jurisdiction management

State machine design with optimistic concurrency control

Zero-downtime database migration strategies (dual password hash formats)

Excel-compatible precision engineering (round-half-up at aggregation boundaries)

Domain-driven development requiring regulatory research (DOL opinion letters, labor law compliance)

Role-based access control with cascading permission hierarchies

Responsive design with mobile-first approach for real-world usage patterns

Future Enhancements

Integration with popular POS systems (Square, Toast, Clover) to eliminate manual tip entry

Comprehensive automated test suite proportional to calculation engine complexity

Expansion of jurisdiction-specific compliance rules beyond New York

Native mobile applications for the employee portal with push notifications

Integration with accounting software (QuickBooks, Xero) for seamless payroll export

AI-powered shift recommendations based on historical staffing and tip data

Advanced analytics dashboard with predictive modeling for tip trends

Multi-language support for international restaurant operations

ProTip — Automated tip distribution and payroll compliance for restaurants, replacing spreadsheets with real-time precision.

Like this project