benzuko

Architecture

Principles

1. Server-first. Components are React Server Components unless they need state, effects, or animation. This keeps the client bundle small.
2. One direction of data. UI → hook → service → HTTP → API route → Zod.
3. Validation at every boundary. Zod schemas in lib/schemas.ts are the single source of truth and export inferred types.
4. Atomic Design. Complexity grows atoms → molecules → organisms → templates → pages.

Folder responsibilities

| Folder | Responsibility | | — | — | | app/ | Routes, layouts, route handlers, SEO metadata. The only place Next.js file conventions live. | | app/(app)/ | Route group for authenticated screens; shares AppShell + error boundary. | | app/api/ | Edge/Node route handlers. Validate, rate-limit, return typed JSON. | | components/atoms | Stateless primitives (Button, Input, Badge, Logo, Skeleton, Spinner). | | components/molecules | Small compositions (StatCard, FormField, OfferRow, NavLink). | | components/organisms | Feature blocks (Navbar, Footer, Hero, OrderBook, ToastRegion). | | components/templates | Page skeletons (MarketingLayout, AppShell). | | components/providers | Client context providers (React Query, Theme). | | hooks/ | Reusable client hooks; React Query wrappers live here. | | lib/ | Cross-cutting infra: env, axios client, query client, rate limit, schemas, logger, constants. | | services/ | Data-access functions. The only layer that talks to lib/api. | | store/ | Zustand stores for UI/session/toast state. | | utils/ | Pure, framework-agnostic helpers. Fully unit-tested. | | types/ | Shared domain + API types. | | styles/ | CSS variable design tokens consumed by Tailwind. |

Data flow example — opening a trade

1. OrderBook (organism) calls useCreateTrade().
2. The hook runs a React Query mutation → services/trades.service.ts.
3. The service POSTs via the shared Axios client (lib/api.ts).
4. app/api/trades/route.ts rate-limits, validates with createTradeSchema, and returns a typed Trade.
5. On success the hook invalidates queries and fires a toast.

Rendering & performance

• output: 'standalone' for small Docker images.
• optimizePackageImports for lucide-react and framer-motion.
• next/font self-hosts Jost/Inter/JetBrains Mono (no layout shift).
• Route-level loading.tsx + Skeleton for perceived performance.
• React Query caching (staleTime 60s) avoids refetch storms.

Security

• CSP, HSTS, X-Frame-Options, X-Content-Type-Options, Referrer-Policy, Permissions-Policy set globally in next.config.js.
• All API input validated; per-client rate limiting.
• React auto-escaping; no dangerouslySetInnerHTML.

This site is open source. Improve this page.