@vatvaghool/create-ipl-dashboard 0.1.0

package/template/app/types/dashboard.ts

@@ -0,0 +1,75 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import type { ComponentType } from "react";
+
+export interface InsightCard {
+  id: string;
+  title: string;
+  note: string;
+  accent: string;
+  icon: ComponentType<{ className?: string }>;
+}
+
+export interface SummaryCard {
+  id: string;
+  title: string;
+  value: string;
+  note: string;
+  accent: string;
+  icon: ComponentType<{ className?: string }>;
+}
+
+export interface ChartItem {
+  label: string;
+  value: number;
+  sublabel: string;
+  difference?: number;
+  fill?: string;
+}
+
+export interface DashboardModel {
+  leader: any; // From OverallChartItem
+  topTeams: any[];
+  normalizedOverall: any[];
+  teamBadges: any;
+  insights: InsightCard[];
+  summaryCards: SummaryCard[];
+  barLeaderboard: ChartItem[];
+  liveBars: ChartItem[];
+  topTeamsChart: ChartItem[];
+  captainTeams: any[];
+  tableRows: any[];
+  liveLeader: any;
+  liveLabel: string;
+  liveChartTitle: string;
+  matchCount: number;
+  hottest: any;
+}
+
+export interface SectionCardProps {
+  title: string;
+  note: string;
+  children: React.ReactNode;
+  className?: string;
+  index: number;
+  icon: ComponentType<{ className?: string }>;
+  accent?: string;
+}
+
+export interface StickyMiniProps {
+  title: string;
+  value: string;
+  note: string;
+  variant: "yellow" | "blue" | "pink";
+  icon: ComponentType<{ className?: string }>;
+}
+
+export interface ChartBoardProps {
+  items: ChartItem[];
+  valueLabel: string;
+  emptyLabel?: string;
+}
+
+export interface LatestBadgeProps {
+  pts: number;
+  isTop: boolean;
+}

package/template/app/types.ts

@@ -0,0 +1,130 @@
+export type OverallChartItem = {
+  name: string;
+  points: number;
+  rank: number;
+  previousRank?: number;
+  previousPoints?: number;
+  lastMatchPoints?: number;
+  gapToNext?: number;
+  gapPercent?: number;
+  movement?: "up" | "down" | "same" | "new";
+  transfersLeft?: number;
+  transfersUsed?: number;
+  totalTransfers?: number;
+  boostersUsed?: string;
+  efficiency?: number;
+  isLastMatchLeader?: boolean;
+  captain?: ScrapedSquadPlayer | null;
+  viceCaptain?: ScrapedSquadPlayer | null;
+  players?: ScrapedSquadPlayer[];
+};
+
+export type DailyChartRow = {
+  day: string;
+  [teamName: string]: string | number;
+};
+
+export type DashboardData = {
+  overall: OverallChartItem[];
+  daily: DailyChartRow[];
+  updatedAt?: string;
+  dailyTransferUpdatedAt?: string;
+  completedMatches?: number;
+  source?: "database";
+  snapshot?: ScrapedDashboardPayload;
+  transfers?: ScrapedTransferSnapshot;
+};
+
+export type RawApiUser = {
+  rno: number;
+  temname: string;
+  points: number;
+  matches: Array<{
+    matchId: number;
+    points: number;
+  }>;
+};
+
+export type TeamRecord = {
+  id: number;
+  name: string;
+  owner: string;
+  fantasyNames: string[];
+};
+
+export type TeamMatchPointsRecord = {
+  teamId: number;
+  matchId: number;
+  points: number;
+};
+
+export type LeaderSnapshotRecord = {
+  teamId: number;
+  rank: number;
+  totalPoints: number;
+  lastMatchPoints?: number;
+  transfersLeft?: number;
+  transfersUsed?: number;
+  totalTransfers?: number;
+  boostersUsed?: string;
+  captain?: ScrapedSquadPlayer | null;
+  viceCaptain?: ScrapedSquadPlayer | null;
+  players?: ScrapedSquadPlayer[];
+  capturedAt?: string;
+};
+
+export type ScrapedSquadPlayer = {
+  name: string;
+  number?: string;
+  points?: number;
+};
+
+export type ScrapedLeaderboardItem = {
+  rank: number;
+  name: string;
+  points: number;
+  matchesPlayed?: number;
+  lastMatchPoints?: number;
+  netPoints?: number;
+  netRank?: number;
+  transfersLeft?: number;
+  transfersUsed?: number;
+  totalTransfers?: number;
+  boostersUsed?: string;
+  captain?: ScrapedSquadPlayer | null;
+  viceCaptain?: ScrapedSquadPlayer | null;
+  players?: ScrapedSquadPlayer[];
+};
+
+export type ScrapedDashboardPayload = {
+  updatedAt?: string;
+  dailyTransferUpdatedAt?: string;
+  completedMatches?: number;
+  leaders: ScrapedLeaderboardItem[];
+};
+
+export type ScrapedTransferItem = {
+  team: string;
+  matchesPlayed: number;
+  boostersUsed: number;
+  transfersLeft: string;
+  updatedAt: string;
+};
+
+export type ScrapedTransferSnapshot = {
+  updatedAt?: string;
+  teams: ScrapedTransferItem[];
+};
+
+export type RawOverviewUser = {
+  name: string;
+  totalPoints: number;
+};
+
+export type RawDailyUser = {
+  name: string;
+  daily: Array<{
+    day: string;
+    points: number;
+  }>;
+};

package/template/app/utils/dashboard/index.ts

@@ -0,0 +1,72 @@
+import { getChartColor } from "../../lib/utils/getChartColor";
+
+export function formatCompactNumber(value: number): string {
+  if (value >= 1000000) {
+    return `${(value / 1000000).toFixed(1)}M`;
+  }
+  if (value >= 1000) {
+    return `${(value / 1000).toFixed(1)}K`;
+  }
+  return value.toString();
+}
+
+export function formatLedgerNumber(value?: number): string {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return "-";
+  }
+
+  return value.toLocaleString("en-IN", {
+    maximumFractionDigits: value % 1 === 0 ? 0 : 1,
+  });
+}
+
+export function formatDateTime(value?: string | null): string {
+  if (!value) {
+    return "just now";
+  }
+
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) {
+    return "just now";
+  }
+
+  return date.toLocaleString("en-IN", {
+    day: "2-digit",
+    month: "short",
+    hour: "2-digit",
+    minute: "2-digit",
+  });
+}
+
+export function getBoosterCount(value?: string): number {
+  if (!value) {
+    return 0;
+  }
+
+  const numeric = Number(value.trim());
+  return Number.isFinite(numeric) && numeric > 0 ? numeric : 0;
+}
+
+export function getTeamColor(index: number, total: number): string {
+  return getChartColor(index, total);
+}
+
+export function createChartData(
+  items: Array<{
+    label: string;
+    value: number;
+    sublabel: string;
+    difference?: number;
+  }>,
+): Array<{
+  label: string;
+  value: number;
+  sublabel: string;
+  difference?: number;
+  fill: string;
+}> {
+  return items.map((item, index) => ({
+    ...item,
+    fill: getChartColor(index, items.length),
+  }));
+}

package/template/eslint.config.mjs

@@ -0,0 +1,18 @@
+import { defineConfig, globalIgnores } from "eslint/config";
+import nextVitals from "eslint-config-next/core-web-vitals";
+import nextTs from "eslint-config-next/typescript";
+
+const eslintConfig = defineConfig([
+  ...nextVitals,
+  ...nextTs,
+  // Override default ignores of eslint-config-next.
+  globalIgnores([
+    // Default ignores of eslint-config-next:
+    ".next/**",
+    "out/**",
+    "build/**",
+    "next-env.d.ts",
+  ]),
+]);
+
+export default eslintConfig;

package/template/infra/cloud-run/README.md

@@ -0,0 +1,68 @@
+# Cloud Run Scraper Job
+
+This folder contains the deployment scaffold for moving the Playwright sync off local machines and scheduled GitHub Actions.
+
+## Files
+
+- `sync-job.yaml`: example Cloud Run Job manifest
+
+The container image is built from the repo root `Dockerfile.sync`.
+
+## Required secrets
+
+Create these in Google Secret Manager before deploying:
+
+- `IPL_POST_SECRET`
+- `IPL_STORAGE_STATE_B64`
+
+`IPL_STORAGE_STATE_B64` should contain the base64-encoded contents of `ipl-auth.json`.
+
+## Required env vars
+
+- `IPL_API_BASE_URL`
+- `IPL_LEAGUE_URL`
+- `IPL_HEADLESS=1`
+
+## Deploy
+
+From the repo root:
+
+```bash
+PROJECT_ID=your-gcp-project \
+REGION=asia-south1 \
+APP_BASE_URL=https://your-app-domain \
+bash scripts/deploy-cloud-run-sync.sh
+```
+
+## Schedule
+
+After the job exists, attach Cloud Scheduler to it on a 5-10 minute cadence:
+
+```bash
+PROJECT_ID=your-gcp-project \
+REGION=asia-south1 \
+SERVICE_ACCOUNT_EMAIL=your-scheduler-sa@your-gcp-project.iam.gserviceaccount.com \
+bash scripts/deploy-cloud-scheduler.sh
+```
+
+## Notes
+
+- The web app should already be deployed with `MONGODB_URI` and `IPL_POST_SECRET`.
+- The scraper job is intentionally separate from the Next.js runtime so browser automation does not compete with web traffic.
+- Run `APP_BASE_URL=https://your-app-domain npm run verify:production` before wiring the scheduler.
+
+## Alerting hook
+
+Use `/api/ops/status` as the primary freshness endpoint.
+
+Suggested alert behavior:
+
+- alert immediately if it returns `503`
+- alert if Cloud Run job executions start failing repeatedly
+- alert if Cloud Scheduler stops invoking the job on schedule
+
+Quick manual check:
+
+```bash
+APP_BASE_URL=https://your-app-domain npm run monitor:ops
+```

package/template/infra/cloud-run/sync-job.yaml

@@ -0,0 +1,32 @@
+apiVersion: run.googleapis.com/v1
+kind: Job
+metadata:
+  name: ipl-sync
+spec:
+  template:
+    spec:
+      template:
+        spec:
+          timeoutSeconds: 1200
+          maxRetries: 1
+          containers:
+            - image: REGION-docker.pkg.dev/PROJECT_ID/ipl-dashboard/ipl-sync:latest
+              env:
+                - name: NODE_ENV
+                  value: production
+                - name: IPL_HEADLESS
+                  value: "1"
+                - name: IPL_LEAGUE_URL
+                  value: https://fantasy.iplt20.com/classic/league/view/66930102
+                - name: IPL_API_BASE_URL
+                  value: https://YOUR_APP_DOMAIN
+                - name: IPL_POST_SECRET
+                  valueFrom:
+                    secretKeyRef:
+                      name: IPL_POST_SECRET
+                      key: latest
+                - name: IPL_STORAGE_STATE_B64
+                  valueFrom:
+                    secretKeyRef:
+                      name: IPL_STORAGE_STATE_B64
+                      key: latest

package/template/infra/cutover/README.md

@@ -0,0 +1,84 @@
+# Production Cutover Checklist
+
+Use this checklist when moving from local/dev operation to the cloud-first production setup.
+
+## 1. Prepare secrets
+
+- Create `MONGODB_URI` for the Vercel project
+- Create `IPL_POST_SECRET` for both Vercel and the scraper job
+- Create `IPL_STORAGE_STATE_B64` in Google Secret Manager
+
+## 2. Deploy the web app
+
+- Import the repo into Vercel
+- Set production env vars
+- Deploy the app
+- Attach the final custom domain
+
+Reference:
+
+- `infra/vercel/README.md`
+
+## 3. Verify the deployed app
+
+Run:
+
+```bash
+APP_BASE_URL=https://your-app-domain npm run verify:production
+```
+
+Expected:
+
+- `/api/ops/status` returns JSON
+- `/api/ipl` returns dashboard data or a structured error
+- `/api/ipl?format=snapshot` returns snapshot data or a structured error
+- `/api/ipl/transfers` returns transfer data or a structured error
+
+## 4. Deploy the scraper job
+
+Run:
+
+```bash
+PROJECT_ID=your-gcp-project \
+REGION=asia-south1 \
+APP_BASE_URL=https://your-app-domain \
+bash scripts/deploy-cloud-run-sync.sh
+```
+
+Reference:
+
+- `infra/cloud-run/README.md`
+
+## 5. Attach the scheduler
+
+Run:
+
+```bash
+PROJECT_ID=your-gcp-project \
+REGION=asia-south1 \
+SERVICE_ACCOUNT_EMAIL=your-scheduler-sa@your-gcp-project.iam.gserviceaccount.com \
+bash scripts/deploy-cloud-scheduler.sh
+```
+
+## 6. Run one manual sync
+
+Trigger the Cloud Run job once manually and confirm:
+
+- `/api/ops/status` shows Mongo connected
+- `/api/ipl?format=snapshot` returns leaders
+- `/api/ipl/transfers` returns teams
+
+## 7. Disable legacy paths
+
+- Keep GitHub Actions sync as manual fallback only
+- Do not rely on local file persistence in production
+- Keep `IPL_WRITE_SEED_DATA_FILE` unset in production
+
+## 8. Monitor after cutover
+
+Watch:
+
+- Vercel function logs
+- Cloud Run job executions
+- Cloud Scheduler execution history
+- MongoDB Atlas metrics

package/template/infra/vercel/README.md

@@ -0,0 +1,57 @@
+# Vercel Deployment
+
+This app is intended to run on Vercel as the web tier and MongoDB Atlas as the live datastore.
+
+## Recommended production shape
+
+- Vercel hosts the Next.js app
+- MongoDB Atlas stores dashboard, raw-user, and transfer data
+- Cloud Run Job runs the Playwright scraper
+- Cloud Scheduler triggers the scraper job
+
+## Required Vercel environment variables
+
+Set these in the Vercel project for the `Production` environment:
+
+- `MONGODB_URI`
+- `IPL_POST_SECRET`
+- `IPL_API_LOG=0`
+- `IPL_API_LOG_PAYLOAD=0`
+- `IPL_DASHBOARD_STALE_MINUTES=20`
+- `IPL_TRANSFERS_STALE_MINUTES=720`
+
+Optional:
+
+- `IPL_WRITE_SEED_DATA_FILE=0`
+
+## Deployment checklist
+
+1. Import the Git repository into Vercel.
+2. Confirm the framework preset is `Next.js`.
+3. Set the root directory to the repository root.
+4. Add the production environment variables listed above.
+5. Deploy once to create the initial project URL.
+6. Add your custom domain.
+7. Verify `GET /api/ops/status` on the deployed domain.
+8. Point the Cloud Run Job to the final app base URL.
+
+## Post-deploy verification
+
+Run:
+
+```bash
+APP_BASE_URL=https://your-app-domain npm run verify:production
+```
+
+Expected production behavior:
+
+- live snapshot writes require MongoDB
+- local snapshot files are ignored
+- the app remains stateless at the web tier
+- `/api/ops/status` returns `503` when dashboard freshness is critically stale
+
+## Notes
+
+- Preview deployments can use a separate MongoDB database if you want realistic previews.
+- Keep `IPL_POST_SECRET` identical between Vercel and the scraper job.
+- The repo root `vercel.json` keeps the deployment contract explicit for the project.

package/template/next.config.ts

@@ -0,0 +1,7 @@
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  /* config options here */
+};
+
+export default nextConfig;