Invoiceflow

InvoiceFlow 💎

High-Performance Invoicing Engine & Automated Payment Recovery Platform

InvoiceFlow is a production-grade invoicing and payment infrastructure platform engineered for freelancers and boutique agencies. It streamlines client billing into a frictionless workflow with instant Stripe/Razorpay checkout links, automated PDF generation, background reminder queues via BullMQ, and real-time webhook telemetry.

---

🏗️ System Architecture

graph TD
    Client[Client / Browser UI] -->|HTTPS / WSS| CDN[Vercel Edge / Static Assets]
    Client -->|REST API Requests| API[Express API Server on Bun]
    
    subgraph Core Engine
        API --> Auth[JWT & Google OAuth2.0]
        API --> Validation[Zod Strict Schemas]
        API --> RateLimiter[Sliding Window Rate Limiter]
        API --> DB[(PostgreSQL Database via Prisma)]
    end
    
    subgraph Async Processing
        API -->|Enqueue Jobs| Redis[(Redis / Upstash)]
        Redis --> Worker[BullMQ Background Worker]
        Worker --> EmailService[Resend Delivery Engine]
        Worker --> PDFEngine[Headless PDF Generator]
    end
    
    subgraph Webhook Ingestion
        Stripe[Stripe / Razorpay Webhooks] -->|HMAC-Signed Events| Ingestion[Idempotent Webhook Handler]
        Ingestion -->|State Machine Update| DB
        Ingestion -->|Trigger Notification| Redis
    end

---

✨ Engineering Highlights

• ⚡ Sub-Millisecond Event Pipeline: Built on Bun and Express with strict Zod validation, ensuring sub-50ms API responses for invoice rendering and payment intent creation.
• 🔄 Idempotent Payment Ingestion: Webhook consumers verify cryptographic HMAC signatures (Stripe-Signature / Razorpay HMAC-SHA256) and enforce database transaction isolation to prevent double-crediting.
• 📬 Background Queue Worker: BullMQ + Redis handles async email dispatch, scheduled reminder escalations, and automated PDF document compilation without blocking the main event loop.
• 🛡️ Multi-Layered Security Core:
  • CSRF Double-Submit Cookie protection (csrf-csrf)
  • Argon2 / BCrypt 12-round salted password hashing with sentinel dummy compare to prevent username enumeration timing attacks
  • Strict tenant isolation on all Prisma queries via user-scoped foreign keys
  • Granular rate-limiting on sensitive auth and payment routes
• 🎨 Glassmorphic Interface: Built with React 19, Tailwind CSS 4, Framer Motion, and TanStack Query with optimistic UI mutations and dark/light system sync.

---

🛠️ Technology Matrix

Subsystem	Stack / Tooling	Purpose
API Core	Bun / Node.js, Express 5, TypeScript	REST endpoints & business logic
Persistence	PostgreSQL (Neon / Supabase), Prisma ORM	ACID-compliant relational storage
Background Jobs	BullMQ, Redis (Upstash)	Scheduled payment reminders & retries
Frontend	React 19, Vite, Tailwind CSS 4, Framer Motion	High-converting client dashboard
Data Fetching	TanStack React Query v5	Cache invalidation, optimistic updates
Email Gateway	Resend API (Domain-verified DKIM/SPF)	Transactional invoice delivery
Payment Gateways	Stripe Checkout, Razorpay	Global USD ($) and local INR (₹) processing
Observability	Pino Structured Logging, Sentry	Request tracing and error profiling

---

🚀 Quickstart & Local Setup

Prerequisites

• Bun (v1.2+) or Node.js (v20+)
• Redis instance (local or Upstash)
• PostgreSQL database

1. Repository Setup

git clone https://github.com/sidsri14/invoiceflow.git
cd invoiceflow

2. Backend Configuration

cd backend
bun install
cp .env.example .env

# Run database migrations
bunx prisma migrate deploy

# Start API server
bun run dev

# In a separate terminal, start background worker
bun run worker

3. Frontend Dashboard

cd ../frontend
npm install
npm run dev

Navigate to http://localhost:5173 to explore the dashboard and interactive demo generator.

---

🧪 Testing & Verification

The test suite covers API response formatting, cryptographic auth workflows, schema validators, and webhook processors:

# Run backend test suite
cd backend
bun test src/__tests__

# Run frontend test suite
cd ../frontend
npm test -- --run

# Run full TypeScript verification & production build
npm run build

Results:

• Backend: 38/38 Unit Tests Passing (2.36s execution time)
• Frontend: 13/13 Vitest Tests Passing, 0 Type Errors across 3,000+ transformed modules

---

📈 Roadmap & Upcoming Extensions

• Public Demo Generator (No-Auth Sandbox)
• Resend Automated Email Reminders & Delivery Telemetry
• Multi-Gateway Ingestion (Stripe + Razorpay)
• Dark / Light Adaptive Theme System
• AI-Powered Invoice Extraction from Receipts (OCR + LLM)
• Multi-Currency Real-time FX Auto-Conversion
• Automated Webhook Dispatch to Custom Endpoints

---

⚖️ License

Distributed under the MIT License. Crafted with precision by Siddharth Srivastava.