PayFlow

📖 Project Overview

Most personal finance applications tell you where your money went. PayFlow focuses on where your money should go.

The application is designed around the payday workflow, helping users answer one simple but important question:

"I just got paid—how should I distribute this money before my next paycheck?"

Using a deterministic planning engine, PayFlow analyzes the user's upcoming bills, recurring expenses, and savings goals, then generates an optimized allocation plan. Funds are distributed across priorities while accounting for due dates, remaining paydays, and available income, ensuring essential obligations are covered before optional spending.

Instead of manually calculating budgets every payday, users receive a complete financial plan in seconds.

✨ Key Features

⚡ Deterministic Payday Planner

Automatically calculates how much money should be allocated to every bill and savings goal based on upcoming due dates and remaining paydays. Handles recurring expenses, variable bills, and shortage scenarios through a priority-based waterfall allocation system.

📅 Financial Calendar

An interactive calendar visualizes upcoming paydays, bills, recurring obligations, and savings deadlines. Each payday displays its current status (Scheduled, Draft, Active, or Completed) and includes a detailed day inspector for reviewing planned allocations.

📋 Payday Execution Workflow

Users can execute their generated payday plan through an interactive checklist, marking transfers and allocations as completed in real time with optimistic UI updates for an instant user experience.

💼 Wallet & Fund Management

Supports multiple wallets while separating physical money storage from financial goals and recurring funds, making budgeting more flexible and organized.

🌙 Modern Responsive Interface

Designed with a responsive mobile-first layout featuring a desktop sidebar, mobile navigation, floating action buttons, and instant dark/light theme switching.

🏗️ Architecture & Engineering

🧠 Planning-First Financial Engine

At the heart of PayFlow is a deterministic calculation engine built with pure TypeScript. The planner computes payday windows, determines how many paydays remain before each due date, evenly distributes recurring obligations, and prioritizes allocations using a waterfall model:

Critical → High → Medium → Optional

This approach ensures financial obligations are funded before discretionary spending while producing consistent results for identical inputs.

🔄 Atomic Database Transactions

Payday confirmation is handled through custom PostgreSQL stored procedures (RPC) in Supabase. Every payday execution—including snapshots, allocation records, and transaction logs—is committed within a single database transaction to guarantee data consistency.

⚡ Optimistic User Experience

React's optimistic rendering enables immediate feedback when completing allocations, providing a responsive interface without waiting for network requests.

🌍 Timezone-Safe Date Calculations

A dedicated date engine normalizes all calculations using UTC, preventing off-by-one errors and ensuring consistent payday planning regardless of user timezone.

🛠️ Technology Stack

Frontend

• Next.js 16 (App Router)

• React 19

• TypeScript

• Tailwind CSS

• Base UI

• Lucide React

• Sonner

• next-themes

Backend

• Supabase

• PostgreSQL

• Supabase Auth

• PostgreSQL RPC Functions

• Row Level Security (RLS)

Architecture

• Server Components

• Server Actions

• Deterministic Planning Engine

• Domain-Driven Data Model

• Optimistic UI

• Responsive Design

Testing & Deployment

• Node.js Test Runner

• Vercel

• GitHub

• TypeScript Strict Mode

💡 Engineering Highlights

• Built a deterministic financial planning engine instead of a traditional expense tracker.

• Designed a domain-driven architecture separating Paydays, Bills, Funds, Wallets, and Allocations into independent modules.

• Implemented atomic PostgreSQL transactions using Supabase RPC to ensure reliable payday execution.

• Developed a UTC-normalized date engine to eliminate timezone-related calculation errors.

• Leveraged Server Components and Server Actions to minimize client-side JavaScript while improving performance and security.

• Created a responsive, production-ready user experience with optimistic UI updates, real-time feedback, and a modern component architecture.

🎯 Outcome

PayFlow transforms payday from a manual budgeting exercise into an automated planning process. By combining deterministic financial calculations, a modern full-stack architecture, and an intuitive user experience, the application provides users with a clear, actionable plan for managing their income before spending begins.

The project demonstrates expertise in full-stack development, system architecture, database design, financial domain modeling, server-side rendering, transactional consistency, and modern React application development.