How dipin13k/penaltyblitz works
Project type & purpose (from tree + README)
• Type: Full-stack Next.js (App Router) application bootstrapped with create-onchain.
• Purpose: A web app that integrates OnchainKit + wallet connectivity (wagmi) and includes server-side capabilities via Next.js Route Handlers under app/api/*.
• Notable integrations hinted by structure:
• Farcaster integration via /.well-known/farcaster.json and a FarcasterInit.tsx component.
• Wallet setup / hidden wallet button UI components.
• Webhook + notify endpoints suggesting external callbacks and push/notify flows.
• Deployment likely to Vercel (vercel.json).
UI / App Router pages
• app/page.tsx, app/layout.tsx, app/page.module.css, app/globals.css
• The core page + global layout and styling.
• app/rootProvider.tsx
• Likely the “composition root” for React context providers (e.g., wagmi client, OnchainKit providers).
• UI components that indicate product features:
• app/WalletSetup.tsx
• app/HiddenWalletButton.tsx
• app/FarcasterInit.tsx
Server-side endpoints (Next.js Route Handlers)
• app/api/auth/route.ts
• app/api/notify/route.ts
• app/api/webhook/route.ts
These are the backend surface area of the app. Treat them as “micro-APIs” hosted within the Next.js runtime.
“Well-known” Farcaster metadata
• app/.well-known/farcaster.json/route.ts
• public/.well-known/farcaster.json
Libraries / configuration / platform
• app/lib/wagmi.ts — wallet client configuration (chains, connectors, transports).
• minikit.config.ts — likely OnchainKit/minikit configuration (treat as integration config).
• vercel.json — deployment topology hint (serverless functions/edge routes on Vercel).
User Agent
• Could be a normal browser and/or Farcaster-compatible client depending on usage.
Next.js React UI
• page.tsx, layout.tsx, CSS modules.
Provider Layer
• rootProvider.tsx (wagmi/OnchainKit providers).
Wallet UX
• WalletSetup.tsx, HiddenWalletButton.tsx
Farcaster initialization
• FarcasterInit.tsx
App Router Server
• Serves SSR/RSC pages and static assets.
Route Handlers (API)
• /api/auth → app/api/auth/route.ts
• /api/notify → app/api/notify/route.ts
• /api/webhook → app/api/webhook/route.ts
Well-known endpoints
• /.well-known/farcaster.json (static and/or dynamic handler)
Blockchain / RPC provider
• Used via wagmi/OnchainKit (Base / Ethereum-compatible chain implied by OnchainKit docs link).
Farcaster
• Consumes /.well-known/farcaster.json and may participate in auth/verification flows.
Architectural patterns to highlight (what makes this repo “tick”)
• Next.js App Router: unified full-stack pattern (UI + API in one codebase).
• Provider-based client architecture: rootProvider.tsx + app/lib/wagmi.ts as the integration nucleus.
• Route Handler-based backend: minimal backend endpoints co-located with app code.
• Externalized trust boundaries:
• Wallet signing + RPC calls are external trust zones.
• Webhook caller is an external trust zone.
• Farcaster is an external trust zone consuming metadata.
Clients
• Browser UI
• Farcaster client (if relevant)
Next.js on Vercel
• App Router (pages/layout)
• API route handlers: auth / notify / webhook
• Well-known endpoint serving
External Services
• Blockchain network + RPC
• Wallet providers
• Farcaster
• Webhook emitter
• Notification service (if used)
• “User device” (client)
• “Vercel runtime” (your server boundary)
• “External systems”
Component granularity (don’t overthink it; split it out)
Even if some components are small, it’s better here to explicitly show:
• Each major external dependency (Blockchain RPC, Farcaster, Webhook source)
Labels
• Use explicit endpoint labels:
• GET /.well-known/farcaster.json
• POST /api/auth
• POST /api/webhook
• POST /api/notify
• “wagmi client (app/lib/wagmi.ts)”
• “OnchainKit/minikit config (minikit.config.ts)”
• “sign + submit tx”
• “read calls (eth_call)”
Clients
• User Browser / Farcaster Client
• Next.js UI (page/layout)
• WalletSetup UI
• FarcasterInit UI
• App Providers (rootProvider: wagmi + OnchainKit)
Next.js (Vercel)
• App Router Rendering
• /.well-known/farcaster.json handler/static file
• API: /api/auth
• API: /api/notify
• API: /api/webhook
External
• Wallet Provider(s)
• Blockchain RPC / Base network
• Farcaster
• Webhook Emitter (3rd party)
• Notification Service (if /api/notify calls out)
Them with the flows described above.