# dipin13k/penaltyblitz architecture

> Architecture diagram of the GitHub repository dipin13k/penaltyblitz, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dipin13k/penaltyblitz
- Repository: https://github.com/dipin13k/penaltyblitz

## Overview

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

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% Clients
  %% =========================
  subgraph "Clients (User Device)"
    direction TB
    User["User Agent (Browser / Farcaster Client)"]:::client

    subgraph "Next.js React UI (Client)"
      direction TB
      UI["App Router UI (page/layout/styles)"]:::frontend
      Providers["Provider Layer (Composition Root)"]:::frontend
      WalletSetup["Wallet Setup UI"]:::frontend
      HiddenWalletBtn["Hidden Wallet Button"]:::frontend
      FarcasterInit["Farcaster Init UI"]:::frontend
      WagmiCfg["wagmi Client Config"]:::config
      MinikitCfg["OnchainKit / minikit Config"]:::config

      UI -->|"wraps"| Providers
      Providers -->|"renders"| WalletSetup
      Providers -->|"renders"| HiddenWalletBtn
      Providers -->|"renders"| FarcasterInit
      Providers -->|"uses"| WagmiCfg
      Providers -->|"uses"| MinikitCfg
    end

    User -->|"HTTPS GET /"| UI
  end

  %% =========================
  %% Next.js on Vercel
  %% =========================
  subgraph "Next.js Server Runtime (Vercel)"
    direction TB
    VercelRuntime["Vercel Hosting (Serverless/Edge Runtime)"]:::runtime
    AppRouter["App Router Rendering (RSC/SSR + Static Assets)"]:::runtime

    subgraph "Route Handlers (app/api/*)"
      direction TB
      AuthAPI["POST /api/auth"]:::api
      NotifyAPI["POST /api/notify"]:::api
      WebhookAPI["POST /api/webhook"]:::api
    end

    subgraph "Farcaster Well-Known Endpoint"
      direction TB
      WellKnownDyn["GET /.well-known/farcaster.json (Dynamic Handler)"]:::api
      WellKnownStatic["GET /.well-known/farcaster.json (Static File)"]:::static
    end

    VercelCfg["Deployment Config"]:::config

    VercelRuntime -->|"hosts"| AppRouter
    VercelRuntime -->|"hosts"| AuthAPI
    VercelRuntime -->|"hosts"| NotifyAPI
    VercelRuntime -->|"hosts"| WebhookAPI
    VercelRuntime -->|"serves"| WellKnownDyn
    VercelRuntime -->|"serves"| WellKnownStatic
    VercelCfg -->|"configures"| VercelRuntime
  end

  %% =========================
  %% External Systems
  %% =========================
  subgraph "External Systems (Trust Boundaries)"
    direction TB
    WalletProviders["Wallet Provider(s) (Injected/Wallet Apps)"]:::external
    BlockchainRPC["Blockchain RPC / EVM Network (e.g., Base)"]:::external
    Farcaster["Farcaster"]:::external
    WebhookEmitter["3rd-Party Webhook Emitter"]:::external
    NotificationSvc["Notification Service"]:::external
  end

  %% =========================
  %% Flows
  %% =========================
  UI -->|"HTTPS (RSC/SSR/assets)"| AppRouter

  Providers -->|"connectWallet()/signMessage()"| WalletProviders
  WalletProviders -->|"RPC (eth_call/eth_sendRawTransaction)"| BlockchainRPC
  Providers -->|"readCalls()/submitTx()"| BlockchainRPC

  UI -->|"POST /api/auth (wallet-based auth)"| AuthAPI
  UI -->|"POST /api/notify (subscribe/send)"| NotifyAPI

  WebhookEmitter -.->|"POST /api/webhook (event callback)"| WebhookAPI
  WebhookAPI -->|"optionalRead/verify"| BlockchainRPC
  WebhookAPI -->|"triggerNotify"| NotificationSvc
  NotifyAPI -->|"send/subscribe"| NotificationSvc

  Farcaster -->|"GET /.well-known/farcaster.json (metadata/verification)"| WellKnownDyn
  Farcaster -->|"GET /.well-known/farcaster.json (metadata/verification)"| WellKnownStatic
  FarcasterInit -->|"initializeIntegration()"| Farcaster

  %% =========================
  %% Click Events (component mapping)
  %% =========================
  click UI "https://github.com/dipin13k/penaltyblitz/blob/main/app/page.tsx"
  click AppRouter "https://github.com/dipin13k/penaltyblitz/blob/main/app/layout.tsx"
  click Providers "https://github.com/dipin13k/penaltyblitz/blob/main/app/rootProvider.tsx"
  click WalletSetup "https://github.com/dipin13k/penaltyblitz/blob/main/app/WalletSetup.tsx"
  click HiddenWalletBtn "https://github.com/dipin13k/penaltyblitz/blob/main/app/HiddenWalletButton.tsx"
  click FarcasterInit "https://github.com/dipin13k/penaltyblitz/blob/main/app/FarcasterInit.tsx"
  click WagmiCfg "https://github.com/dipin13k/penaltyblitz/blob/main/app/lib/wagmi.ts"
  click MinikitCfg "https://github.com/dipin13k/penaltyblitz/blob/main/minikit.config.ts"
  click AuthAPI "https://github.com/dipin13k/penaltyblitz/blob/main/app/api/auth/route.ts"
  click NotifyAPI "https://github.com/dipin13k/penaltyblitz/blob/main/app/api/notify/route.ts"
  click WebhookAPI "https://github.com/dipin13k/penaltyblitz/blob/main/app/api/webhook/route.ts"
  click WellKnownDyn "https://github.com/dipin13k/penaltyblitz/blob/main/app/.well-known/farcaster.json/route.ts"
  click WellKnownStatic "https://github.com/dipin13k/penaltyblitz/blob/main/public/.well-known/farcaster.json"
  click VercelCfg "https://github.com/dipin13k/penaltyblitz/blob/main/vercel.json"

  %% =========================
  %% Styles
  %% =========================
  classDef client fill:#dbeafe,stroke:#1d4ed8,stroke-width:1px,color:#0b1220
  classDef frontend fill:#bfdbfe,stroke:#1d4ed8,stroke-width:1px,color:#0b1220
  classDef runtime fill:#e9d5ff,stroke:#7c3aed,stroke-width:1px,color:#0b1220
  classDef api fill:#ddd6fe,stroke:#6d28d9,stroke-width:1px,color:#0b1220
  classDef static fill:#f3e8ff,stroke:#7c3aed,stroke-width:1px,color:#0b1220,stroke-dasharray: 4 3
  classDef external fill:#e5e7eb,stroke:#374151,stroke-width:1px,color:#0b1220
  classDef config fill:#cffafe,stroke:#0ea5e9,stroke-width:1px,color:#0b1220
```
