KakoFinds

The Ultimate Finds & Reps Spreadsheet
Discover 5,700+ products · Compare prices across agents · Build hauls

🌐 Live App · ✨ Features · 🛠️ Tech Stack · 🚀 Getting Started

📖 Overview

KakoFinds is a full-stack web application that serves as a comprehensive product discovery platform for replica fashion finds. Users can browse, search, filter, and compare thousands of products across multiple purchasing agents (Kakobuy, CNFans, Oopbuy, ACBuy), save favorites, and build personalized haul lists.

The platform is built with Next.js 16 App Router, uses Supabase as the database layer, Clerk for authentication, and is deployed on Vercel at kakofinds.app.

✨ Features

🛍️ Product Discovery

5,700+ Products — Browse an extensive catalog of streetwear, sneakers, accessories, and more
Fuzzy Search — Typo-tolerant search powered by Fuse.js with debounced API queries
Advanced Filtering — Filter by 15 categories, price range (USD slider), QC photos availability, and sort options
Paginated API — Server-side pagination with configurable page sizes

🔗 Multi-Agent Price Comparison

4 Supported Agents — Kakobuy, CNFans, Oopbuy, ACBuy
Smart Link Generation — Automatic affiliate link construction with marketplace detection (Weidian, Taobao, 1688)
Agent Selector — Users can switch between agents and get direct purchase links

👤 User Features (Clerk Auth)

Favorites — Save and manage favorite products with optimistic UI updates, synced to server
Hauls — Create, rename, duplicate, and delete personalized product haul lists (up to 20 per user, synced via Clerk metadata)
Search History — Per-user search history stored in localStorage (up to 8 entries)

🎨 UI/UX

Dark Theme — Premium dark design with neutral color palette and glassmorphism effects
Galaxy Background — Interactive WebGL particle system (Three.js/OGL) on desktop with mouse repulsion
Framer Motion Animations — Scroll-reveal animations, smooth transitions, and micro-interactions
Responsive Design — Fully responsive from mobile to desktop with mobile-optimized lightweight backgrounds
Spotlight Search Modal — CMD+K inspired search with keyboard navigation, trending searches, quick actions, and category shortcuts
QC Photo Gallery — Dedicated quality check photo gallery for products
Infinite Scroll Ticker — Horizontal auto-scrolling trending products carousel
Custom Scrollbar — Styled WebKit scrollbar matching the dark theme
Cookie Consent — GDPR-compliant cookie consent banner

📧 Contact System

Resend Email API — Contact form submissions sent via Resend
Cloudflare Turnstile — Bot protection with CAPTCHA verification
Rate Limiting — In-memory IP-based rate limiting (3 requests/hour per IP)
Input Sanitization — HTML escape and validation for all form fields

📊 Analytics & Monitoring

Discord Webhooks — Real-time visit logging and unique visitor tracking via Discord embeds
IP Geolocation — Visitor location detection for analytics
Unique Visitor Counter — Cookie-based unique visitor identification with server-side logging

🔍 SEO

Dynamic Metadata — Per-page OpenGraph, Twitter Cards, and structured data (JSON-LD)
Dynamic Sitemap — Auto-generated sitemap including all product pages
robots.txt — Configured crawler directives
PWA Manifest — Web app manifest for installability
Schema.org — Product structured data with offers, ratings, and organization markup
Canonical URLs — Proper canonical tags on all pages

🛠️ Tech Stack

Core Framework

Technology	Version	Purpose
Next.js	16.1.6	Full-stack React framework (App Router, RSC, API Routes)
React	19.2.3	UI library with React Compiler enabled
TypeScript	5.x	Static type checking

Styling & UI

Technology	Purpose
Tailwind CSS v4	Utility-first CSS framework
shadcn/ui (New York style)	Pre-built accessible component library
Radix UI	Headless UI primitives (Dialog, Dropdown, Select, Sheet, etc.)
Lucide React	Icon library
React Icons	Additional icons
Framer Motion	Animation library
tw-animate-css	Tailwind CSS animation utilities
next-themes	Theme management

Backend & Data

Technology	Purpose
Supabase	PostgreSQL database with auto-generated REST API
Clerk	Authentication, user management, metadata storage
Resend	Transactional email delivery
Cloudinary	Image hosting and optimization

Search & Data Processing

Technology	Purpose
Fuse.js	Client-side fuzzy search engine
PapaParse	CSV parsing
ExcelJS / SheetJS	Excel/spreadsheet processing
Cheerio	HTML parsing and scraping

State Management

Technology	Purpose
Zustand	Lightweight state management (favorites, hauls, agent selection)

3D & Visual Effects

Technology	Purpose
Three.js	3D WebGL rendering engine
OGL	Minimal WebGL framework (Galaxy effect)

Security & Bot Protection

Technology	Purpose
Cloudflare Turnstile	CAPTCHA alternative for bot protection
Discord Webhooks	Real-time traffic monitoring

DevOps & Tooling

Technology	Purpose
ESLint v9	Code linting
PostCSS	CSS processing pipeline
Puppeteer	Headless browser for scraping/testing
React Compiler (Babel plugin)	Automatic memoization and optimization

📁 Project Structure

KakoFinds/
├── app/                          # Next.js App Router
│   ├── api/                      # API Routes
│   │   ├── contact/route.ts      #   Contact form (Resend + Turnstile)
│   │   ├── haul/[userId]/        #   Haul CRUD operations
│   │   ├── log-unique/           #   Unique visitor logging
│   │   ├── products/route.ts     #   Product search/filter/paginate API
│   │   └── user/                 #   User favorites & hauls sync
│   │       ├── favorites/        #     Favorites management
│   │       └── hauls/            #     Hauls management
│   ├── browse/                   # Product browse page with filters
│   ├── contact/                  # Contact form page
│   ├── cookies/                  # Cookie policy page
│   ├── favorites/                # User favorites page
│   ├── haul/                     # Single haul view
│   ├── hauls/                    # Hauls management page
│   ├── privacy/                  # Privacy policy page
│   ├── product/[id]/             # Dynamic product detail page
│   ├── terms/                    # Terms of service page
│   ├── globals.css               # Global styles & CSS variables
│   ├── layout.tsx                # Root layout (Clerk, Header, Footer)
│   ├── manifest.ts               # PWA manifest
│   ├── not-found.tsx             # Custom 404 page
│   ├── page.tsx                  # Homepage
│   ├── robots.ts                 # robots.txt generation
│   └── sitemap.ts                # Dynamic sitemap generation
├── components/                   # React components
│   ├── modals/                   # Modal components
│   │   ├── add-to-haul-modal.tsx #   Add product to haul modal
│   │   └── create-haul-modal.tsx #   Create new haul modal
│   ├── ui/                       # shadcn/ui base components
│   │   ├── galaxy.tsx            #   WebGL galaxy particle effect
│   │   ├── button.tsx            #   Button variants (CVA)
│   │   ├── dialog.tsx            #   Dialog/modal primitive
│   │   ├── slider.tsx            #   Price range slider
│   │   └── ...                   #   17 UI primitives total
│   ├── header.tsx                # Navigation header with search
│   ├── hero-section.tsx          # Homepage hero with Galaxy BG
│   ├── product-card.tsx          # Product card component
│   ├── product-filters.tsx       # Category/sort/price filters
│   ├── product-grid.tsx          # Product grid with pagination
│   ├── search-modal.tsx          # Spotlight-style search modal
│   ├── trending-products.tsx     # Trending products section
│   └── ...                       # 27 components total
├── hooks/                        # Custom React hooks
│   └── use-favorites.ts          # Favorites Zustand store
├── lib/                          # Utility libraries
│   ├── agent-utils.ts            # Multi-agent link generation
│   ├── auth.ts                   # Authentication helpers
│   ├── constants.ts              # Category translations & sort options
│   ├── cors.ts                   # CORS middleware for API routes
│   ├── currency.ts               # CNY → PLN conversion
│   ├── discord.ts                # Discord webhook utility
│   ├── products.ts               # Supabase product queries
│   ├── supabase.ts               # Supabase client init
│   └── utils.ts                  # General utilities (cn)
├── store/                        # Zustand stores
│   ├── agent-store.ts            # Selected agent state
│   ├── useHaulModals.ts          # Haul modal state
│   └── useHauls.ts               # Hauls CRUD with Clerk sync
├── types/                        # TypeScript type definitions
│   └── index.ts                  # Product, FilterState, Haul types
├── data/                         # Static data
│   └── stats.json                # Site statistics
├── public/                       # Static assets
│   ├── brands/                   # Agent brand logos
│   ├── logo.svg                  # KakoFinds logo (SVG)
│   ├── logo.png                  # KakoFinds logo (PNG)
│   └── og-image-main.png         # OpenGraph preview image
├── middleware.ts                  # Clerk auth + visit logging middleware
├── next.config.ts                # Next.js configuration
├── components.json               # shadcn/ui configuration
├── tsconfig.json                 # TypeScript configuration
├── postcss.config.mjs            # PostCSS configuration
└── package.json                  # Dependencies & scripts

🚀 Getting Started

Prerequisites

Node.js ≥ 18.x
npm (or yarn/pnpm)
A Supabase project with a products table
A Clerk application
(Optional) Resend, Cloudinary, Cloudflare Turnstile accounts

Installation

# Clone the repository
git clone https://github.com/DEV-industry/KakoFinds.git
cd KakoFinds

# Install dependencies
npm install

Environment Variables

Create a .env.local file in the project root:

# Clerk Authentication
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_live_...
CLERK_SECRET_KEY=sk_live_...

# Supabase Database
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key

# Cloudinary (Image Hosting)
NEXT_PUBLIC_CLOUDINARY_CLOUD_NAME=your-cloud-name
CLOUDINARY_API_KEY=your-api-key
CLOUDINARY_API_SECRET=your-api-secret

# Discord Webhooks (Analytics)
DISCORD_WEBHOOK_VISITS=https://discord.com/api/webhooks/...
DISCORD_WEBHOOK_UNIQUE=https://discord.com/api/webhooks/...

# Google Gemini AI
GEMINI_API_KEY=your-gemini-key

# Cloudflare Turnstile (Bot Protection)
NEXT_PUBLIC_CLOUDFLARE_SITE_KEY=your-site-key
CLOUDFLARE_SECRET_KEY=your-secret-key

# Resend (Email)
RESEND_API_KEY=re_...

# Internal
INTERNAL_API_KEY=your-internal-secret

Database Schema

The Supabase products table should include these columns:

Column	Type	Description
`id`	`text` (PK)	Unique product identifier
`name`	`text`	Product name
`category`	`text`	Category (Polish: Buty, Koszulki, etc.)
`price`	`text`	Formatted price string
`price_usd_value`	`numeric`	Parsed USD value for sorting/filtering
`image`	`text`	Main product image URL
`kakobuy_url`	`text`	Original Kakobuy product link
`oopbuy_url`	`text`	Oopbuy product link
`acbuy_url`	`text`	ACBuy product link
`qc_images`	`text[]`	Array of QC photo URLs

Running Locally

# Start the development server
npm run dev

The app will be available at http://localhost:3000.

Building for Production

# Create production build
npm run build

# Start production server
npm start

🔌 API Reference

`GET /api/products`

Fetch products with search, filtering, sorting, and pagination.

Parameter	Type	Default	Description
`page`	`number`	`1`	Page number
`limit`	`number`	`24`	Items per page
`search`	`string`	`""`	Fuzzy search query
`category`	`string`	`""`	Filter by category
`sort`	`string`	`""`	`price_asc` or `price_desc`
`qcOnly`	`boolean`	`false`	Show only products with QC photos
`minPrice`	`number`	`0`	Minimum USD price
`maxPrice`	`number`	`99999`	Maximum USD price
`keywords`	`string`	—	Comma-separated keyword filter
`random`	`boolean`	`false`	Shuffle results

Response:

{
  "products": [...],
  "total": 5700,
  "page": 1,
  "totalPages": 238,
  "hasMore": true
}

`POST /api/contact`

Submit a contact form message. Requires Cloudflare Turnstile token. Rate-limited to 3 requests per IP per hour.

`POST /api/user/favorites`

Add or remove a product from user favorites. Requires authenticated Clerk session.

`GET/POST /api/user/hauls`

CRUD operations for user haul lists. Requires authenticated Clerk session.

🏗️ Architecture

┌─────────────────────────────────────────────────────┐
│                    Client (Browser)                  │
│  ┌──────────┐  ┌───────────┐  ┌──────────────────┐  │
│  │ React 19 │  │ Zustand   │  │ Framer Motion    │  │
│  │ RSC + CC  │  │ Stores    │  │ Animations       │  │
│  └────┬─────┘  └─────┬─────┘  └──────────────────┘  │
│       │              │                                │
│  ┌────┴──────────────┴──────────────────────────┐    │
│  │         Next.js 16 App Router                │    │
│  │  Server Components · API Routes · Middleware │    │
│  └──────────────┬───────────────────────────────┘    │
└─────────────────┼───────────────────────────────────┘
                  │
    ┌─────────────┼─────────────────┐
    │             │                 │
    ▼             ▼                 ▼
┌────────┐  ┌─────────┐  ┌──────────────┐
│Supabase│  │  Clerk  │  │  External    │
│  (DB)  │  │ (Auth)  │  │  Services   │
│        │  │         │  │             │
│Products│  │Users    │  │• Resend     │
│Table   │  │Metadata │  │• Cloudinary │
│        │  │Sessions │  │• Discord    │
│        │  │         │  │• Turnstile  │
└────────┘  └─────────┘  └──────────────┘

Key Architectural Decisions

Server Components by default — Product pages, browse, and detail views are Server Components for optimal performance and SEO
Client Components where needed — Interactive elements (search modal, filters, favorites, hauls) use "use client" directive
Optimistic Updates — Favorites and haul operations update the UI instantly, then sync to the server with automatic rollback on failure
Chunked Data Fetching — Products are fetched in 1,000-row chunks from Supabase to handle large datasets
Middleware Pipeline — Clerk auth + visit tracking + unique visitor detection run on every request
Haul Data in Clerk Metadata — Haul lists are stored in Clerk's unsafeMetadata for simplicity, avoiding separate DB tables

🎨 Design System

The app uses a carefully crafted dark-first design system with CSS custom properties:

Token	Light	Dark
`--background`	`#ffffff`	`#0a0a0a`
`--foreground`	`#0a0a0a`	`#fafafa`
`--card`	`#ffffff`	`#141414`
`--muted`	`#f5f5f5`	`#1f1f1f`
`--border`	`#e5e5e5`	`#262626`
`--primary`	`#0a0a0a`	`#fafafa`
`--destructive`	`#ef4444`	`#ef4444`

Typography: Inter — loaded via next/font/google for optimal performance.

Component Library: shadcn/ui (New York variant) with Radix UI primitives.

📜 Available Scripts

Command	Description
`npm run dev`	Start development server with hot reload
`npm run build`	Create optimized production build
`npm start`	Run production server
`npm run lint`	Run ESLint code analysis

🌍 Deployment

The application is deployed on Vercel with the following configuration:

Framework: Next.js (auto-detected)
Build Command: next build
Domain: kakofinds.app
Environment Variables: Set via Vercel dashboard
Image Domains: Configured for Unsplash, Cloudinary, Google, Yupoo, and Geilicdn

📄 License

Built with ❤️ by KakoFinds

Name		Name	Last commit message	Last commit date
Latest commit History 101 Commits
app		app
components		components
data		data
hooks		hooks
lib		lib
public		public
store		store
types		types
.gitignore		.gitignore
README.md		README.md
components.json		components.json
eslint.config.mjs		eslint.config.mjs
middleware.ts		middleware.ts
next.config.ts		next.config.ts
package-lock.json		package-lock.json
package.json		package.json
page_source.html		page_source.html
postcss.config.mjs		postcss.config.mjs
tsconfig.json		tsconfig.json
verify-ids.ts		verify-ids.ts

Folders and files

Latest commit

History

Repository files navigation

KakoFinds

📖 Overview

✨ Features

🛍️ Product Discovery

🔗 Multi-Agent Price Comparison

👤 User Features (Clerk Auth)

🎨 UI/UX

📧 Contact System

📊 Analytics & Monitoring

🔍 SEO

🛠️ Tech Stack

Core Framework

Styling & UI

Backend & Data

Search & Data Processing

State Management

3D & Visual Effects

Security & Bot Protection

DevOps & Tooling

📁 Project Structure

🚀 Getting Started

Prerequisites

Installation

Environment Variables

Database Schema

Running Locally

Building for Production

🔌 API Reference

GET /api/products

POST /api/contact

POST /api/user/favorites

GET/POST /api/user/hauls

🏗️ Architecture

Key Architectural Decisions

🎨 Design System

📜 Available Scripts

🌍 Deployment

📄 License

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`GET /api/products`

`POST /api/contact`

`POST /api/user/favorites`

`GET/POST /api/user/hauls`

Packages