Tippable Developer Documentation

Architecture overview and technical implementation guide

Overview

Tippable is a digital tipping platform that enables businesses to collect and distribute tips to their workers through QR codes and unique tipping URLs. Workers can track their earnings in real-time, request instant payouts, and manage their profiles. Administrators can oversee multiple workers, configure tip pooling strategies, generate QR codes, and analyze tipping trends.

Technical Stack: This is an MVP using a Node/Express/Postgres backend and a Next.js frontend.

Tipping Flow

The public tipping experience is the core user-facing feature, allowing customers to leave tips for workers without requiring authentication.

Page: /tip/[workerId]

This is a dynamic route that displays a tipping interface for a specific worker. The page fetches worker information and displays their name, role, and photo. Customers can select from suggested tip amounts or enter a custom amount.

Hook: usePublicTipping

This custom hook manages the public tipping flow state and API interactions:

  • Fetches worker details via GET /api/workers/:workerId
  • Handles tip submission logic
  • Manages loading and error states
  • Returns worker data and tip submission function

API Endpoint: POST /api/tips

Receives tip submissions from the public tipping page. The request payload includes:

{ "workerId": "uuid", "amount": 10.00, "customerName": "John Doe" }

Important: The amount is sent in dollars and stored as cents in the database to avoid floating-point precision issues.

The backend converts dollars to cents, validates the worker exists and is active, creates the tip record, and returns a success response.

Worker Flow

Workers have access to a protected dashboard where they can view their tips, earnings, and request instant payouts. Authentication is handled via JWT tokens.

Pages

/worker/login

Authentication page where workers enter their email and password. Upon successful login, a JWT token is stored and used for subsequent API requests.

/worker/dashboard

Main dashboard showing earnings overview, recent tips, stats cards, and instant payout functionality. Displays daily, weekly, and monthly earnings with trend indicators.

/worker/settings

Profile management page where workers can update their name, role, photo URL, and password. Changes are persisted immediately.

Hooks

useWorkerAuth

Manages worker authentication state, handles login/logout, and stores JWT token in localStorage. Provides authentication context throughout the worker portal.

useWorkerDashboard

Fetches and manages worker dashboard data including profile, recent tips, earnings stats, and payout information. Handles loading states and error handling.

Backend Endpoints

POST
/api/auth/worker/login

Authenticates worker credentials and returns JWT token

GET
/api/worker/me

Returns authenticated worker profile

GET
/api/worker/me/tips

Returns paginated list of tips received by worker

GET
/api/worker/me/stats

Returns earnings statistics (daily, weekly, monthly) with trends

POST
/api/worker/me/payouts/instant

Initiates instant payout request for available balance

Admin Flow

Administrators have full control over the platform, including worker management, analytics, settings configuration, and QR code generation. The admin portal is protected and requires admin authentication.

Pages

/admin/login

Admin authentication page. Credentials are validated and JWT token is issued.

/admin/dashboard

Overview dashboard showing total tips, active workers, pending approvals, and recent tipping activity. Provides quick stats and navigation to other admin features.

/admin/workers

Worker management interface for approving pending workers, deactivating accounts, and viewing worker details. Supports filtering and bulk actions.

/admin/analytics

Visual analytics dashboard with charts showing tips by day and tips by role. Includes summary statistics and trend analysis.

/admin/settings

Configuration page for business profile, tipping settings (default suggestions, payout schedule), and tip distribution strategies (individual vs pooled).

/admin/qr

QR code generation page for all active workers. Supports printing and downloading QR codes for physical distribution.

Hooks

useAdminAuth

Manages admin authentication state, handles login/logout, and stores JWT token. Provides admin context and protects admin routes.

useAdminDashboard

Fetches comprehensive dashboard data including stats, workers list, recent tips, and analytics. Consolidates multiple API calls into a single hook.

Backend Endpoints Summary

POST
/api/auth/admin/login

Authenticates admin and returns JWT token

GET
/api/admin/stats

Returns platform-wide statistics for dashboard

GET
/api/admin/workers

Returns list of all workers with filtering

GET
/api/admin/analytics

Returns analytics data (tips by day, tips by role)

GET
/api/admin/settings

Returns current admin/business settings

GET
/api/admin/pooling-settings

Returns tip pooling configuration

Data Model

The database schema consists of four main entities that model the tipping workflow:

Employer

Represents a business account that manages workers and receives tips. Contains business profile information, branding settings, default tip configurations, and payout schedules.

Worker

Individual service workers who receive tips. Each worker has a unique tipping URL, belongs to an employer, has a role designation, and maintains a status (pending, active, inactive). Workers authenticate separately and can view their personal earnings.

Tip

Records each individual tip transaction. Links a tip amount to a specific worker, stores the customer name (optional), timestamps the transaction, and tracks the tip status (pending, completed, refunded). Amounts are stored in cents to avoid floating-point errors.

Payout

Tracks payout requests and transfers to workers. Contains the payout amount, worker reference, payout method (instant, scheduled), status tracking (pending, processing, completed, failed), and external payment processor references (e.g., Stripe transfer ID).

Stripe & Payments (Future)

The current implementation is a functional MVP without live payment processing. Stripe integration will be added to enable real money transactions. Here are the planned integration points:

Tip Creation

When a customer submits a tip via POST /api/tips, the backend will:

  • Create a Stripe Payment Intent for the tip amount
  • Return client secret to frontend for payment confirmation
  • Frontend displays Stripe Elements for secure payment collection
  • Store Stripe charge ID with tip record for reconciliation

Payouts

When workers request payouts via POST /api/worker/me/payouts/instant, the backend will:

  • Use Stripe Connect to transfer funds to worker accounts
  • Create Stripe Transfer or Payout objects
  • Track transfer status and update payout records
  • Handle instant payouts (higher fee) vs scheduled payouts
  • Workers will need to complete Stripe Connect onboarding

Webhooks

A webhook endpoint at POST /api/webhooks/stripe will handle Stripe events:

  • payment_intent.succeeded - Mark tip as completed
  • payment_intent.payment_failed - Mark tip as failed
  • transfer.paid - Mark payout as completed
  • transfer.failed - Mark payout as failed and notify worker
  • Webhook signatures will be verified for security

Note: All payment-related features are currently simulated. No actual money is transferred in the MVP. Stripe integration requires additional configuration including API keys, Connect platform setup, and compliance verification.