← back

My First Programming Project

Pricing calculator diagram

Project Overview

The Discount Payments calculator is a web-based pricing estimate tool for small business payment processing costs. It provides transparent, cost-plus pricing estimates by calculating interchange fees from major card networks (Visa, Mastercard, Amex, Interac) plus a transparent markup. The tool takes business inputs (monthly sales, transaction size, business type) and generates detailed breakdowns with PDF export capabilities.

Technologies Used

  • Frontend: Next.js 15 with React 19 and TypeScript for type-safe development
  • UI/Styling: Tailwind CSS with Radix UI components for accessible, responsive design
  • Database: Supabase (PostgreSQL) for calculation persistence and tracking
  • PDF Generation: @react-pdf/renderer for professional report creation
  • Testing: Vitest for unit tests, Playwright for E2E testing
  • Deployment: Vercel for hosting and continuous deployment

Key Technical Decisions & Architecture

Separation of Concerns: The calculator uses a modular architecture with clear boundaries between:

  • Logic (pure calculation functions)
  • Configuration (immutable pricing data)
  • UI (React components)
  • API (database operations)
  • Data (MCC processing pipeline)

Feature-Slice Architecture: Organized by domain features rather than technical layers, with each feature being self-contained.

How It Works: Core Flow

  1. User Input Collection: Business name (optional), monthly sales volume, average transaction size, and MCC code selection
  2. Transaction Distribution: Splits transactions 50/50 between credit (Visa 50%, Mastercard 42%, Amex 8%) and debit (Interac)
  3. Network-Specific Calculations: Each card network applies its own interchange rate rules based on business size, MCC category, and card type
  4. Cost Aggregation: Combines all network costs, adds assessment fees and markup
  5. Persistence & Output: Saves calculation with unique Quote ID, generates interactive results and PDF export

Key Concepts Involved

Cost-Plus Pricing: Transparent markup over actual interchange rates rather than flat percentage fees

MCC (Merchant Category Code): 4-digit codes categorizing ~300 business types that determine interchange rates

Interchange Rates: Complex tiered pricing from card networks based on business size, transaction volume, and risk factors

Quote Lifecycle: Each calculation gets a unique ID for tracking, PDF generation, and audit trails

Version Control: Both calculator logic and pricing data are versioned for reproducibility

Implementation: Only current.json is mutable and points to the active pricing model. All other config files are versioned snapshots.

Separate Network Calculators

Architecture: Each card network (Visa, Mastercard, Amex, Interac) has its own dedicated calculator module with specialized logic.

Why Separated:

  • Network Complexity: Each network has fundamentally different rules (e.g., Visa's 4 product categories vs. Amex's MCC-based tiers)
  • Independent Evolution: Networks update rates independently without cross-contamination
  • Specialized Logic: Each calculator implements network-specific rules without conditional branching
  • Testability: Networks can be tested in isolation with dedicated test suites
  • Parallel Processing: Orchestrator runs all network calculations concurrently

Example Differences: Visa uses consumer/business/corporate/prepaid categories; Amex applies transaction-size tiers; Mastercard has charity exemptions; Interac includes chip/tap and flash fee tiers.

API Routes

Core Endpoint: /api/calculate (POST)

  • Validates input at API boundary for security
  • Calls calculation logic and persists results to database
  • Returns calculation ID and display-ready results
  • Tracks user metadata (IP, user agent) for analytics

Supporting Endpoints:

  • /api/download-pdf: Generates and serves PDF reports by quote ID
  • /api/email-pdf: Future feature for PDF delivery (currently tracks email intent)

Data Flow: API routes serve as thin controllers calling domain logic, with validation and error handling at boundaries.

MCC Search Box Data Pipeline

Data Sources:

  • Raw data from Visa's Merchant Data Standards Manual (300+ business categories)
  • Enriched with search keywords and similarity relationships

Pipeline Process:

  1. Raw Data (mcc.raw.json): MCC codes, categories, descriptions, examples, keywords, similarity links
  2. Enrichment Script (buildMccData.ts):
    • Builds searchable text blobs (normalized lowercase, diacritic-free)
    • Enforces bidirectional similarity relationships
    • Validates MCC code formats
  3. Enriched Output (mcc.enriched.json): App-ready data with searchText fields

Search Implementation:

  • Primary Matches: Direct text search through combined MCC data (limited to 25 results)
  • Similarity Expansion: Shows related MCC codes for broader discovery
  • Popular Categories: Default display when no search query
  • Real-time Filtering: Client-side search with instant results

Technical Details: Precomputed search text includes code + category + description + examples + keywords. Normalization removes punctuation, collapses whitespace, and handles accents for robust matching.

Versioning & Deployment

  • Calculator Logic: Git tags with Semantic Versioning (e.g., v1.2.0)
  • Pricing Data: Date-based immutable files with pointer system
  • Deployment: Vercel with automated builds and database migrations
  • Testing: Comprehensive unit tests for logic, E2E tests for user flows

This architecture ensures the calculator remains accurate, maintainable, and trustworthy for business decision-making.