# worldrepublicorg/mini-app architecture

> Architecture diagram of the GitHub repository worldrepublicorg/mini-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/worldrepublicorg/mini-app
- Repository: https://github.com/worldrepublicorg/mini-app

## Overview

##### 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”).

## Diagram (Mermaid)

```mermaid
graph TB
  %% Client Browser Layer
  subgraph "Client Browser"
    direction TB
    Pages["Next.js App Router Pages"]:::ui
    click Pages "https://github.com/worldrepublicorg/mini-app/tree/main/app/[lang]/"
    subgraph "i18n Loader"
      direction TB
      Translations["useTranslations Hook"]:::ui
      click Translations "https://github.com/worldrepublicorg/mini-app/blob/main/hooks/useTranslations.ts"
      Dictionaries["Locale Dictionaries"]:::ui
      click Dictionaries "https://github.com/worldrepublicorg/mini-app/blob/main/app/[lang]/dictionaries/index.ts"
    end
    subgraph "React UI Components"
      direction TB
      PollCard["PollCard Component"]:::ui
      click PollCard "https://github.com/worldrepublicorg/mini-app/blob/main/components/PollCard.tsx"
      PartyList["PoliticalPartyList Component"]:::ui
      click PartyList "https://github.com/worldrepublicorg/mini-app/blob/main/components/PoliticalPartyList.tsx"
      WalletAuth["WalletAuth Component"]:::ui
      click WalletAuth "https://github.com/worldrepublicorg/mini-app/blob/main/components/WalletAuth.tsx"
    end
    subgraph "Context & Providers"
      direction TB
      WalletCtx["WalletContext"]:::ui
      click WalletCtx "https://github.com/worldrepublicorg/mini-app/blob/main/components/contexts/WalletContext.tsx"
      PartiesCtx["PartiesContext"]:::ui
      click PartiesCtx "https://github.com/worldrepublicorg/mini-app/blob/main/components/contexts/PartiesContext.tsx"
      NextAuthProv["NextAuth Provider"]:::ui
      click NextAuthProv "https://github.com/worldrepublicorg/mini-app/blob/main/components/providers/next-auth-provider.tsx"
      MiniKitProv["MiniKit Provider"]:::ui
      click MiniKitProv "https://github.com/worldrepublicorg/mini-app/blob/main/components/providers/minikit-provider.tsx"
      ToastProv["ToastProvider"]:::ui
      click ToastProv "https://github.com/worldrepublicorg/mini-app/blob/main/components/providers/ToastProvider.tsx"
      ErudaProv["Eruda Debug Provider"]:::ui
      click ErudaProv "https://github.com/worldrepublicorg/mini-app/blob/main/components/providers/Eruda/eruda-provider.tsx"
    end
  end

  %% Next.js Serverless Layer
  subgraph "Next.js Serverless"
    direction TB
    AuthRoute["/api/auth/[...nextauth]"]:::server
    click AuthRoute "https://github.com/worldrepublicorg/mini-app/blob/main/app/api/auth/[...nextauth]/route.ts"
    NonceRoute["/api/nonce"]:::server
    click NonceRoute "https://github.com/worldrepublicorg/mini-app/blob/main/app/api/nonce/route.ts"
    CompleteSIWE["/api/complete-siwe"]:::server
    click CompleteSIWE "https://github.com/worldrepublicorg/mini-app/blob/main/app/api/complete-siwe/route.ts"
    MeRoute["/api/me"]:::server
    click MeRoute "https://github.com/worldrepublicorg/mini-app/blob/main/app/api/me/route.ts"
    VerifyRoute["/api/verify"]:::server
    click VerifyRoute "https://github.com/worldrepublicorg/mini-app/blob/main/app/api/verify/route.ts"
  end

  %% External Services & Blockchain
  subgraph "External & Blockchain"
    direction TB
    WorldID["Worldcoin World ID Service"]:::external
    EthereumNet["Ethereum Network (RPC)"]:::external
    VIEM["viemClient"]:::external
    click VIEM "https://github.com/worldrepublicorg/mini-app/blob/main/lib/viemClient.ts"
  end

  %% Static Data Layer
  subgraph "Static Data"
    direction TB
    Elections["elections.ts"]:::data
    click Elections "https://github.com/worldrepublicorg/mini-app/blob/main/data/elections.ts"
    PartiesData["parties.ts"]:::data
    click PartiesData "https://github.com/worldrepublicorg/mini-app/blob/main/data/parties.ts"
    Payouts["payouts.ts"]:::data
    click Payouts "https://github.com/worldrepublicorg/mini-app/blob/main/data/payouts/payouts.ts"
  end

  %% Shared Utilities
  subgraph "Shared Utilities & Types"
    direction TB
    DictUtil["dictionary.ts"]:::data
    click DictUtil "https://github.com/worldrepublicorg/mini-app/blob/main/lib/dictionary.ts"
    Types["types.ts"]:::data
    click Types "https://github.com/worldrepublicorg/mini-app/blob/main/lib/types.ts"
    Utils["utils.ts"]:::data
    click Utils "https://github.com/worldrepublicorg/mini-app/blob/main/lib/utils.ts"
  end

  %% Data Flows
  Pages -->|"loads locale"| Translations
  Pages -->|"imports dictionaries"| Dictionaries
  Pages -->|"renders UI"| PollCard
  Pages -->|"renders UI"| PartyList
  Pages -->|"renders UI"| WalletAuth
  PollCard --> WalletCtx
  PartyList --> PartiesCtx
  WalletAuth --> WalletCtx
  WalletAuth --> AuthRoute
  WalletAuth --> NonceRoute
  CompleteSIWE --> MeRoute
  WalletAuth --> CompleteSIWE
  WalletAuth --> VerifyRoute
  VerifyRoute -->|HTTPS REST| WorldID
  PollCard -->|on-chain calls| VIEM
  VIEM -->|JSON-RPC| EthereumNet
  Pages -->|SSR import| Elections
  Pages -->|SSR import| PartiesData
  Pages -->|SSR import| Payouts

  %% Styles
  classDef ui fill:#cce5ff,stroke:#004085,color:#004085
  classDef server fill:#d4edda,stroke:#155724,color:#155724
  classDef external fill:#fff3cd,stroke:#856404,color:#856404
  classDef data fill:#e2e3e5,stroke:#6c757d,color:#6c757d
```
