KHEL Console: ZK Gaming Analytics Dashboard

KHEL Console is a high-performance, read-only dashboard designed to provide real-time visibility into the ZK Gaming Platform's database. Built with Next.js 15, Prisma, and Tailwind CSS, it visualizes game performance, player acquisition, and ZK-proof verification status.

🚀 Technical Stack

• Framework: Next.js 16.2.4 (App Router)
• Database: PostgreSQL (Supabase)
• ORM: Prisma
• UI Components: Shadcn UI (Radix UI) + Lucide Icons
• Visuals: Tremor / Tailwind CSS
• Package Manager: pnpm

📁 Project Structure

The project uses a consolidated flat structure to minimize monorepo overhead while maintaining clear separation of concerns:
dashboard-console/
├── prisma/ # Database schema and migrations
├── src/
│ ├── app/ # Next.js pages, layouts, and server actions
│ ├── components/ # UI layer (Dashboard, Tables, Filters)
│ ├── lib/ # Core logic (Prisma Singleton, Data Fetchers)
│ ├── types/ # TypeScript interfaces
│ └── utils/ # Formatting and helper functions
├── .env # Environment variables (DB credentials)
├── next.config.ts # Next.js configuration
└── package.json # Dependencies and scripts

⚙️ Core Architecture

1. Direct-to-DB Fetching

To maximize performance and reduce TTI (Time To Interactive), this project utilizes Next.js Server Components. Data is fetched directly from the database using Prisma inside server components, bypassing the need for a separate REST or tRPC API layer for initial page loads.

2. The Prisma Singleton

To prevent connection exhaustion during development (HMR) and in serverless environments, we implement a Singleton pattern in src/lib/db.ts. This ensures a single connection pool is shared across the application.

3. Dual-Path Leaderboard Logic

• All-Time: Reads from the PlayerGameLeaderboard table (cached/indexed).
• Filtered (Today/Week/Custom): Aggregates real-time data from the SessionPlayer table based on specific time-bounds and gameId.

🛠 Setup & Installation

Prerequisites

• Node.js 20+
• pnpm 9+
• A Supabase/PostgreSQL instance with the provided schema applied.

Step 1: Clone and Install

git clone <repository-url>
cd dashboard-console
pnpm install

Step 2: Environment Configuration

Create a .env file in the root directory:
# Transaction Pooler (Used for runtime)
DATABASE_URL="postgres://postgres.[ID]:[PASS]@[aws-0.pooler.supabase.com:6543/postgres?pgbouncer=true](https://aws-0.pooler.supabase.com:6543/postgres?pgbouncer=true)"

# Direct Connection (Used for Prisma migrations)
DIRECT_URL="postgres://postgres.[ID]:[PASS]@db.[ID].supabase.co:5432/postgres"

Step 3: Initialize Database

Generate the Prisma client based on the local schema:
npx prisma generate

🏃 Running the Project

Development

pnpm dev

The dashboard will be available at http://localhost:3000.

Build for Production

pnpm build
pnpm start

🚢 Deployment

1. Database: Ensure your Supabase instance is accessible and the connection pooler is enabled.
2. Platform: Deploy to Vercel or any Next.js-compatible provider.
3. Env Vars: Configure DATABASE_URL and DIRECT_URL in the deployment settings.
4. Read-Only: It is highly recommended to use a database user with SELECT only permissions for the production DATABASE_URL.

📊 Dashboard Metrics Map

Board	Metric	Database Table
Main	Total Games	games
Main	Unique Players	proof_players (Distinct Address)
Sub	Session Volume	game_sessions (Status: FINISHED)
Sub	Active Players	proof_players (Filtered by range)
Sub	New Players	proof_players (First appearance in range)

Note: Sub-board metrics utilize a "Two-Window Fetch" to calculate trend percentages (Current vs. Previous Period).