benzuko

# benzuko **global payments. digital freedom.** The escrow-backed marketplace for digital money — buy and sell PayPal, Wise, Skrill, USDT and 40+ balances peer-to-peer, with every trade held in escrow until both sides confirm. [](./.github/workflows/deploy.yml)   

---

Table of contents

• Overview
• Tech stack
• Quick start
• Scripts
• Environment variables
• Folder structure
• Architecture
• Testing
• Deployment
• Documentation
• Versioning & releases
• Contributing
• Future improvements
• License

Overview

benzuko is a production-ready Next.js 15 (App Router) foundation for a fintech marketplace. It ships a monochrome-luxury design system, an authenticated app shell (dashboard · P2P exchange · wallet), a validated + rate-limited API layer, first-class error handling, security headers, and a full test + CI/CD pipeline.

Scope note: this repository is a frontend + edge-API foundation. Real money movement, persistent escrow ledgers, KYC/AML pipelines and payment-rail integrations belong in dedicated backend services — see Future improvements.

Tech stack

| Layer | Choice | | — | — | | Framework | Next.js 15 · App Router · React 19 | | Language | TypeScript (strict) | | Styling | TailwindCSS 3 · CSS variable tokens · dark mode | | Animation | Framer Motion | | State | Zustand (persisted) | | Data fetching | TanStack React Query · Axios | | Forms & validation | React Hook Form · Zod | | Icons | lucide-react | | Testing | Jest · React Testing Library · Playwright | | Tooling | ESLint (flat) · Prettier · Husky-ready | | Deploy | Vercel · Netlify · Cloudflare · Docker |

Quick start

# 1. clone
git clone https://github.com/your-org/benzuko.git
cd benzuko

# 2. env
cp .env.example .env.local

# 3. install
npm install

# 4. run
npm run dev        # http://localhost:3000

Requires Node 18.18+ (Node 20 recommended).

Scripts

| Command | Description | | — | — | | npm run dev | Start the dev server | | npm run build | Production build (standalone output) | | npm run start | Serve the production build | | npm run lint | ESLint | | npm run typecheck | tsc --noEmit | | npm run test | Jest unit + component tests | | npm run test:coverage | Tests with coverage | | npm run test:e2e | Playwright end-to-end tests | | npm run format | Prettier write |

Environment variables

Copy .env.example → .env.local. All are optional with safe defaults so a fresh clone builds immediately. See docs/ENVIRONMENT.md.

Variable	Default	Purpose
NEXT_PUBLIC_APP_URL	http://localhost:3000	Canonical URL (SEO, metadata)
NEXT_PUBLIC_APP_NAME	BENZUKO	Display name
API_BASE_URL	.../api	Server-side API base
RATE_LIMIT_WINDOW_MS	60000	Rate-limit window
RATE_LIMIT_MAX	60	Max requests per window
AUTH_SECRET	—	Auth signing secret (production)

Folder structure

benzuko/
├── app/                  # App Router: routes, layouts, API, SEO
│   ├── (app)/            # Authenticated shell group (dashboard, p2p, wallet)
│   ├── api/              # Route handlers (health, offers, trades)
│   ├── layout.tsx        # Root layout + fonts + providers
│   ├── page.tsx          # Marketing landing
│   ├── error.tsx         # 500 boundary   not-found.tsx  loading.tsx
│   ├── robots.ts sitemap.ts manifest.ts   # SEO
├── components/           # Atomic Design
│   ├── atoms/ molecules/ organisms/ templates/ providers/
│   └── error-boundary.tsx
├── hooks/                # React hooks (query, theme, media, toast)
├── lib/                  # env, api client, query client, rate-limit, schemas
├── services/             # Data-access layer (offers, trades, auth)
├── store/                # Zustand stores (ui, auth, toast)
├── utils/                # Pure helpers (cn, format, retry)
├── types/                # Shared TypeScript types
├── styles/               # Design tokens
├── public/               # Static assets
├── assets/               # Brand source assets
├── docs/                 # Architecture, API, components, hooks, deployment
├── tests/                # unit · components · e2e
├── .github/workflows/    # CI/CD
└── [config files]        # next, ts, tailwind, eslint, prettier, docker, vercel…

Each folder is explained in docs/ARCHITECTURE.md.

Architecture

• Rendering: Server Components by default; client boundaries only where interactivity/animation is required.
• Data flow: UI → hooks (React Query) → services → Axios → API route → Zod.
• State: ephemeral UI/session state in Zustand (persisted); server state in React Query. No prop-drilling.
• Design: Atomic Design; a single monochrome token set drives light/dark.
• Safety: Zod at every boundary, rate limiting on APIs, strict CSP/HSTS.

Full write-up: docs/ARCHITECTURE.md.

Testing

npm run test         # Jest + RTL
npm run test:e2e     # Playwright (Chromium + mobile)

Unit tests cover utilities and the rate limiter; component tests cover atoms; E2E covers the landing page, P2P route, and the health endpoint.

Deployment

One-liners below; full guide in docs/DEPLOYMENT.md.

Vercel (recommended)

npm i -g vercel && vercel --prod

Netlify — configured via netlify.toml (uses @netlify/plugin-nextjs). Cloudflare Pages — build npm run build, framework preset Next.js. Docker

docker compose up --build   # http://localhost:3000

Documentation

| Doc | Contents | | — | — | | docs/ARCHITECTURE.md | Folder-by-folder + data flow | | docs/API.md | Every endpoint, schema, error code | | docs/COMPONENTS.md | Every component + props | | docs/HOOKS.md | Every hook | | docs/ENVIRONMENT.md | Every env var | | docs/DEPLOYMENT.md | GitHub, Vercel, Netlify, Cloudflare, Docker |

Versioning & releases

Semantic Versioning. History in CHANGELOG.md.

git tag -a v1.0.0 -m "benzuko 1.0.0"
git push origin v1.0.0

Contributing

See CONTRIBUTING.md and CODE_OF_CONDUCT.md.

Future improvements

• Real auth (NextAuth/Clerk) + session middleware and route protection.
• Postgres + Prisma escrow ledger and trade state machine service.
• KYC/AML/OFAC pipeline with OCR + liveness (dedicated microservice).
• Payment-rail integrations (Stripe, Wise, PayPal, Binance Pay).
• Redis-backed rate limiting and Socket.IO real-time trade chat.
• Merchant API + signed webhooks + typed SDK.
• Observability (OpenTelemetry, Sentry) and feature flags.

License

MIT © 2026 benzuko.

This site is open source. Improve this page.