How worldrepublicorg/mini-app works
Project type and purpose
• This is a full-stack Next.js (App Router) application template integrated with MiniKit, NextAuth (SIWE), Worldcoin (World ID) and an Ethereum client (via viem).
• It provides a multilingual polling/governance/earn platform: users authenticate (SIWE/World ID), browse polls, stake with permits, view parties and elections, and earn rewards via on-chain interactions.
File structure
• Top-level directories:
• app/ ⟶ Next.js App-Router pages, grouped by [lang] for i18n (SSR + client components).
• app/api/ ⟶ Next.js serverless API routes (auth, nonce, verify, “me”, complete-siwe).
• components/ ⟶ React UI: atoms, molecules, contexts (WalletContext, PartiesContext), providers (NextAuth, Eruda, Toast), and domain cards (PollCard, PoliticalPartyList).
• data/ ⟶ Static TS data (elections, parties, payouts).
• lib/ ⟶ Shared utilities (dictionary loader, type defs, viemClient for Ethereum RPC).
• hooks/ ⟶ Custom hook useTranslations for loading locale dictionaries.
• Config and styling (tailwind.config.ts, postcss, eslint, tsconfig).
Key README insights
• Uses .env for NEXTAUTH_URL, World ID app credentials, and Dev Portal API keys.
• Authentication flow: NextAuth + SIWE + World ID.
• MiniKit integration for mobile UI.
• No external database—static data in code; on-chain state via viemClient.
Main components
A. Client (Browser/Mobile)
• React UI (pages + components) served by Next.js.
• i18n loader (useTranslations + dictionaries).
• Authentication UI (WalletAuth, Sign-in with World ID).
B. Next.js Server (Serverless / Vercel)
• App Router (SSR/SSG pages).
• API Routes:
– /api/nonce, /api/complete-siwe (SIWE flow)
– /api/auth/[...nextauth] (NextAuth handlers)
– /api/me (session info)
– /api/verify (World ID verification)
• NextAuth Next.js Provider.
C. On-chain Client
• viemClient in lib/viemClient.ts → Ethereum JSON-RPC node or Infura/Alchemy endpoints.
D. External Services
• Worldcoin World ID Developer Portal (Action / verification endpoints).
• Ethereum network (via RPC).
E. Static Data Layer
• data/elections.ts, data/parties.ts, data/payouts/payouts.ts (imported at build/SSR time).
Interactions & data flows
1. User opens browser → Next.js front-end → SSR or client render with locale dictionaries.
2. For authenticated routes: UI triggers Sign-in → NextAuth API route → returns nonce → user signs with wallet (SIWE) → /api/complete-siwe → session cookie.
3. UI calls /api/verify to confirm World ID action → calls external World ID service → confirmation → back to UI.
4. UI calls on-chain actions via lib/viemClient (stake/permit, read/write polls) → Ethereum RPC → chain.
5. UI fetches static data from data/… TS files at build/SSR.
Architectural patterns & design principles
• Separation of concerns:
• Presentation (app/pages + components/ui)
• State management / Contexts (WalletContext, PartiesContext)
• Business logic in API routes and lib utils
• Data (static / on-chain)
• Serverless functions for authentication and verification.
• i18n: directory-based locales + React context/hook.
• Micro-frontend approach for each language root.
Essential elements
• Labeled components (e.g., “app/api/complete-siwe → Serverless Function”).