TipFlow Manager

Business

Original Idea

Smart Tip Pooling A web app that calculates pooled tips by role and time and exports payroll-ready totals.

Product Requirements Document (PRD): TipFlow Manager

1. Executive Summary

TipFlow Manager is a specialized B2B SaaS platform designed to automate the complex process of tip pooling for the hospitality industry. By replacing error-prone spreadsheets with a robust calculation engine, TipFlow Manager enables restaurant managers to distribute tips based on role-weighted point systems and actual hours worked. The platform ensures 100% mathematical accuracy, provides immutable audit trails for legal compliance, and generates payroll-ready exports for major providers like Gusto and ADP.

2. Problem Statement

Manual tip pooling is a high-friction administrative task in restaurants. Current processes rely on "Excel magic" that is difficult to audit, prone to "penny-loss" rounding errors, and lacks transparency. This leads to:

  • Employee Distrust: Staff feel tips are calculated unfairly or incorrectly.
  • Compliance Risk: Lack of an audit trail for manual adjustments poses legal risks.
  • Operational Inefficiency: Managers spend 3–5 hours per week manually calculating distributions instead of focusing on floor operations.

3. Goals & Success Metrics

  • Goal 1: Accuracy. Eliminate the "Dust Problem" (fractional cent leftovers) using the Hamilton Method.
    • Metric: 0% variance between "Total Pool In" and "Total Pool Distributed."
  • Goal 2: Efficiency. Reduce time spent on tip administration.
    • Metric: Average time to generate a daily tip report < 5 minutes.
  • Goal 3: Integration. Streamline the "POS to Payroll" pipeline.
    • Metric: 90% of users successfully export payroll-ready files without manual formatting.

4. User Personas

  • The Busy Manager (Elena): Needs to quickly input shift data and lock the pool so she can get back to the floor. Values speed and "bulk" actions.
  • The Skeptical Server (Marcus): Wants to know exactly why they received $42.50 vs $50.00. Values transparency and breakdown of the "point value."
  • The Accountant (David): Needs to ensure all data maps perfectly to payroll codes and that no manual adjustments were made without a documented reason.

5. User Stories

  • As a Manager, I want to assign "Point Weights" to different roles (e.g., Bartender = 1.5, Busser = 0.8) so that the pool is distributed according to skill and responsibility level.
  • As a Manager, I want to bulk-paste shift data from my POS so that I don't have to manually type in hours for 40 employees.
  • As a Manager, I want to add a manual adjustment to a server's tip (e.g., for a late-shift trade) and provide a reason so that the audit trail remains intact.
  • As an Accountant, I want to export a CSV formatted specifically for Gusto so that I can upload it and run payroll in seconds.

6. Functional Requirements

6.1 Role-Based Weighted System

  • Ability to create custom roles (Server, Bartender, Runner, etc.).
  • Assign decimal-based point weights to each role (e.g., 1.0, 1.25, 2.0).
  • Logic must calculate Total Weighted Points = Sum(Hours * Weight) for the entire pool.

6.2 The Calculation Engine (Hamilton Method)

  • The system must calculate pro-rata shares using high-precision arithmetic.
  • Dust Management: Remaining fractional cents must be distributed to employees with the largest remainders (Hamilton Method/Largest Remainder) to ensure the pool matches to the cent.

6.3 Data Ingestion & Bulk Entry

  • Excel-style grid for manual entry of Employee, Role, and Hours.
  • Clipboard support (Ctrl+C/V) for pasting data from POS exports.
  • Conflict detection for overlapping shifts or duplicate employee IDs.

6.4 Reporting & Exports

  • PDF Export: Detailed breakdown of the point value ($/point) and individual shares.
  • CSV Export: Formatted templates for Gusto and ADP (including mandatory headers like SOR and roleCode for ADP).

6.5 Immutable Audit Log

  • Every change to a finalized report must be logged.
  • Manual overrides require a "Reason Code" before the record can be saved.

7. Technical Requirements

7.1 Tech Stack (Early 2026 Standards)

  • Frontend: React v19.2.1 (utilizing React Compiler and Actions API).
  • Styling: Tailwind CSS v4.1.18 (Oxide engine, CSS-first configuration).
  • Backend: Node.js v24.13.0 (LTS "Krypton").
  • Database: PostgreSQL v18.1 (utilizing JSONB for audit states and ACID-compliant transactions).
  • Precision Math: decimal.js or dinero.js for all financial calculations (No native Floating Point math).

7.2 Core Architecture

  • State Management: TanStack Query v6 for optimistic updates on bulk shift entries.
  • Authentication: Clerk (Organization-based multi-tenancy for restaurant groups).
  • PDF Generation: Playwright (Headless Chromium) using Browser Contexts for high-concurrency export generation.
  • CSV Generation: Fast-CSV for memory-efficient streaming of large payroll files.

7.3 Integrations

  • Square API: Webhook-based integration (labor.timecard.updated) to fetch declared tips and hours.
  • Toast API: Polling-based integration (every 30 mins) to /labor/shifts to sync hours.
  • Payroll: OAuth 2.0 flow for Gusto; Mutual SSL/TLS (mTLS) with X.509 certificates for ADP.

8. Data Model

Entity: Employee

  • id: UUID
  • external_id: String (POS/Payroll ID)
  • full_name: String
  • default_role_id: UUID (Foreign Key)

Entity: Role

  • id: UUID
  • name: String (e.g., "Bartender")
  • point_weight: Decimal (e.g., 1.50)

Entity: TipPoolReport

  • id: UUID
  • date: Date
  • total_pool_amount: Integer (Stored in Cents)
  • point_value: Decimal
  • status: Enum (Draft, Locked, Exported)
  • audit_log: JSONB (Stores before/after states)

9. API Specification (Sample)

POST /api/v1/reports/:id/calculate

  • Description: Runs the weighted distribution algorithm.
  • Request Body: 
    {
  "total_tips": 500000, // $5,000.00
  "shifts": [
    { "employee_id": "uuid", "hours": 6.5, "role_weight": 1.2 }
  ]
}
  • Response: 
    {
  "point_value": 12.45,
  "distributions": [
    { "employee_id": "uuid", "amount": 8092, "remainder": 0.5 }
  ]
}

10. UI/UX Requirements

  • High-Density Grid: A spreadsheet-like interface for shift entry using virtualized rows (via TanStack Table) to prevent lag during bulk entry.
  • The "Sticky Action Bar": A floating bar appearing upon row selection for "Bulk Role Update" or "Bulk Approve."
  • Transparency Tooltip: Hovering over a calculated total shows the math: (Hours * Weight) * Point Value.
  • Audit Sidebar: A slide-out panel showing the history of manual adjustments for the current report.

11. Non-Functional Requirements

  • Precision: All financial calculations must be handled as integers (cents) to avoid IEEE 754 rounding errors.
  • Security: Role-Based Access Control (RBAC). Servers can only see their own earnings; Managers see the full house.
  • Auditability: Database triggers must prevent any DELETE or UPDATE on the audit_log table (Immutable).

12. Out of Scope

  • Direct Bank Transfers: The app prepares data for payroll but does not move money via ACH/Wire.
  • Scheduling: The app is not a scheduling tool (use integrations like 7shifts).
  • Cash Management: Tracking physical cash drawer counts (focus is on tip distribution logic only).

13. Risks & Mitigations

  • Risk: POS API Downtime.
    • Mitigation: Implement a "Bulk Paste" CSV/Excel fallback so managers can still process tips if Toast/Square APIs are down.
  • Risk: Rounded Cent Variance.
    • Mitigation: Use the Hamilton Method to force-distribute remainders, ensuring the system never "creates" or "loses" a penny.
  • Risk: ADP Certificate Expiry.
    • Mitigation: Automated alerting 30 days before X.509 certificate expiration for the mTLS connection.

14. Implementation Tasks

Phase 1: Project Setup

  • [ ] Initialize project with React v19.2.1 and Vite
  • [ ] Set up Tailwind CSS v4.1.18 with Oxide engine
  • [ ] Configure Node.js v24.13.0 LTS environment
  • [ ] Initialize PostgreSQL v18.1 database with uuid-ossp and pgcrypto extensions

Phase 2: Core Calculation Engine

  • [ ] Implement WeightedDistributionService using decimal.js
  • [ ] Build the Hamilton Method algorithm for "dust" distribution
  • [ ] Create unit test suite for edge-case distributions (e.g., zero-hour shifts, 0.01 total pool)
  • [ ] Implement DB schema for Roles, Employees, and Reports

Phase 3: Bulk Data Entry UI

  • [ ] Build high-density grid component using TanStack Table
  • [ ] Implement Clipboard API integration for Excel/CSV pasting
  • [ ] Create real-time validation for "startTime < endTime" logic
  • [ ] Add "Sticky Action Bar" for bulk row modifications

Phase 4: Audit & Security

  • [ ] Integrate Clerk for Multi-Tenant Auth (Organizations)
  • [ ] Create PostgreSQL triggers for immutable audit logs
  • [ ] Build "Adjustment Reason" modal for manual overrides
  • [ ] Implement RBAC middleware for API endpoints

Phase 5: Integrations & Exports

  • [ ] Build Square/Toast OAuth and data ingestion workers
  • [ ] Implement Playwright-based PDF report generation (with Browser Contexts)
  • [ ] Create Fast-CSV streaming service for Gusto/ADP exports
  • [ ] Configure mTLS certificate handling for ADP Production environment

Phase 6: Polish & Launch

  • [ ] Run 1,000-row stress test on calculation engine
  • [ ] Finalize "Transparency Tooltip" for employee trust
  • [ ] Conduct SOC2-compliant log verification
  • [ ] Deploy to Vercel (Frontend) and AWS RDS/App Runner (Backend)