Merge pull request #216 from blockful/dashboard-metrics

feat: add dashboard metrics

Author: LeonardoVieira1630

PR_DESCRIPTION.md

@@ -0,0 +1,43 @@
+# Dashboard Metrics Implementation
+
+## Summary
+
+Adds a read-only Next.js dashboard for viewing notification system metrics. Provides real-time insights into user growth, DAO subscriptions, notification activity, and user engagement through interactive charts and tables.
+
+## Features
+
+- **Metrics**: Summary stats, user growth tracking, DAO analytics, notification activity, channel distribution
+- **User Management**: User table with ENS name resolution and address tracking
+- **Security**: Read-only database access with query validation (only `SELECT` operations allowed)
+- **UI**: Modern Next.js 14 app with Recharts visualizations (bar, line, pie charts) and Tailwind CSS
+- **Performance**: Query caching (5min TTL), ENS resolution caching, batch processing
+
+## Tech Stack
+
+- Next.js 14 (App Router), TypeScript, Tailwind CSS, Recharts
+- PostgreSQL read-only connection
+- Cookie-based authentication via `DASHBOARD_SECRET`
+
+## API Endpoints
+
+- `GET /api/metrics/summary` - Overall system metrics
+- `GET /api/metrics/growth` - User growth over time
+- `GET /api/metrics/users` - User details with pagination
+- `GET /api/metrics/daos` - DAO subscription metrics
+- `GET /api/metrics/notifications-by-dao` - Notification distribution
+- `GET /api/metrics/notification-activity` - Activity timeline
+- `POST /api/auth` - Authentication
+
+## Testing
+
+✅ Comprehensive test coverage for metrics functions and ENS resolver  
+✅ All packages build successfully
+
+## Environment Variables
+
+```env
+DATABASE_URL=postgresql://...      # Read-only PostgreSQL connection
+DASHBOARD_SECRET=your-secret-here # Authentication password
+```
+
+**Note**: No database migrations required. Dashboard connects to existing database in read-only mode.

apps/dashboard/README.md

@@ -0,0 +1,114 @@
+# Dashboard
+
+A read-only dashboard for viewing notification system metrics.
+
+## Read-Only Enforcement
+
+**This dashboard is strictly read-only and never writes to the database.**
+
+### Safety Measures
+
+1. **Query Validation**: All database queries are validated to ensure only `SELECT` and `WITH` statements are executed
+2. **API Routes**: All metrics API routes are `GET` requests only
+3. **No Write Operations**: The codebase contains no `INSERT`, `UPDATE`, `DELETE`, `CREATE`, `ALTER`, `DROP`, or other write operations
+
+### Database Access
+
+- The dashboard connects to the database using a read-only connection
+- All queries go through the `query()` function in `src/lib/db.ts` which validates read-only operations
+- Any attempt to execute a write operation will throw an error
+
+### Authentication
+
+- The dashboard uses cookie-based authentication (no database writes)
+- Login credentials are validated against `DASHBOARD_SECRET` environment variable
+- Authentication cookies are set in memory only
+
+## Database Queries Guide
+
+This section documents every database query used by the dashboard and the intent
+behind each one. If the schema changes, use this to map the same business
+meaning to the new model.
+
+All queries live in `src/lib/metrics.ts` and are read-only.
+
+### Summary Metrics
+
+- Users total: `SELECT COUNT(*) FROM users`
+  - Goal: total number of user records in the system.
+- Active subscriptions total: `SELECT COUNT(*) FROM user_preferences WHERE is_active = true`
+  - Goal: total active DAO subscriptions across all users.
+- Active addresses total: `SELECT COUNT(*) FROM user_addresses WHERE is_active = true`
+  - Goal: total active blockchain addresses linked to users.
+- Notifications total: `SELECT COUNT(*) FROM notifications`
+  - Goal: total notifications created (all time).
+
+### Channel Distribution
+
+- Query: `SELECT channel, COUNT(*) FROM users GROUP BY channel ORDER BY count DESC`
+  - Goal: how many users exist per channel (e.g., slack, telegram, etc.).
+
+### Engagement Distribution (addresses per user)
+
+- Query built by `buildEngagementDistributionQuery()`
+  - Goal: histogram of users grouped by number of active addresses.
+  - Uses `user_addresses` grouped by `user_id` with `is_active = true`.
+
+### User Growth (daily new users)
+
+- Query: `SELECT date_trunc('day', created_at), COUNT(*) FROM users GROUP BY day ORDER BY day`
+  - Goal: daily new user signups; turned into a cumulative series for charts.
+
+### Top DAOs by active subscribers
+
+- Query in `getTopDaos()`
+  - Source: `user_preferences`
+  - Filters: `is_active = true`, `dao_id` not null/empty, `TRIM(dao_id)`
+  - Goal: highest subscriber counts per DAO.
+
+### Notification Activity by Day
+
+- Query built by `buildNotificationActivityByDayQuery(daoId?)`
+  - Source: `notifications`
+  - Optional filter: `dao_id = $1`
+  - Goal: daily notification counts globally or for a specific DAO.
+
+### Notification Activity by DAO
+
+- Query in `buildNotificationActivityByDaoQuery(limit)`
+  - Source: `notifications`
+  - Aggregation: `COUNT(DISTINCT event_id)` grouped by trimmed `dao_id`
+  - Goal: most active DAOs by number of distinct notification events.
+
+### Users List + Filters (metrics table)
+
+- Queries built by `buildUsersQueries()`
+  - Base sources: `users`, `user_addresses`, `user_preferences`, `channel_workspaces`
+  - Joins:
+    - Addresses per user (active addresses + array of addresses)
+    - DAO preferences per user (active dao count + array of dao_ids)
+    - Slack workspace name via `channel_workspaces`
+  - Filters:
+    - DAO filter via `user_preferences` (active only)
+    - Channel filter via `users.channel`
+    - Address filter via `user_addresses.address` (active only)
+    - Min/Max addresses via computed address_count
+  - Goal: paginated list of users with derived metrics and filters for the UI.
+
+## Development
+
+```bash
+npm run dev
+```
+
+## Build
+
+```bash
+npm run build
+```
+
+## Environment Variables
+
+- `DATABASE_URL` - PostgreSQL connection string (read-only access recommended)
+- `DASHBOARD_SECRET` - Password for dashboard access
+

apps/dashboard/env.example

@@ -0,0 +1,2 @@
+DATABASE_URL=postgresql://user:pass@localhost:5432/notification
+DASHBOARD_SECRET=change-me

apps/dashboard/next-env.d.ts

@@ -0,0 +1,5 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/app/building-your-application/configuring/typescript for more information.

apps/dashboard/next.config.js

@@ -0,0 +1,6 @@
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  reactStrictMode: true,
+};
+
+module.exports = nextConfig;

apps/dashboard/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@notification-system/dashboard",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev -p 3300",
+    "build": "next build",
+    "start": "next start",
+    "test": "tsx --test src/**/*.test.ts"
+  },
+  "dependencies": {
+    "next": "^14.2.5",
+    "pg": "^8.16.3",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "recharts": "^2.13.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.12.12",
+    "@types/react": "^18.3.12",
+    "@types/react-dom": "^18.3.1",
+    "autoprefixer": "^10.4.20",
+    "postcss": "^8.4.49",
+    "tailwindcss": "^3.4.14",
+    "tsx": "^4.19.4",
+    "typescript": "^5.8.3"
+  }
+}

apps/dashboard/postcss.config.js

@@ -0,0 +1,6 @@
+module.exports = {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+};

apps/dashboard/public/favicon.svg

@@ -0,0 +1,39 @@
+import { NextRequest, NextResponse } from 'next/server';
+
+import { getAuthCookieValue } from '../../../lib/auth';
+
+export async function POST(request: NextRequest) {
+  const secret = process.env.DASHBOARD_SECRET;
+  if (!secret) {
+    return NextResponse.json(
+      { error: 'DASHBOARD_SECRET is not configured.' },
+      { status: 500 }
+    );
+  }
+
+  const formData = await request.formData();
+  const password = formData.get('password');
+
+  if (typeof password !== 'string' || password !== secret) {
+    return NextResponse.redirect(new URL('/login?error=1', request.url));
+  }
+
+  const cookieValue = await getAuthCookieValue();
+  if (!cookieValue) {
+    return NextResponse.json(
+      { error: 'Failed to generate auth cookie.' },
+      { status: 500 }
+    );
+  }
+
+  const response = NextResponse.redirect(new URL('/', request.url));
+  response.cookies.set('dashboard_auth', cookieValue, {
+    httpOnly: true,
+    sameSite: 'lax',
+    path: '/',
+    secure: process.env.NODE_ENV === 'production',
+    maxAge: 60 * 60 * 24 * 7,
+  });
+
+  return response;
+}

apps/dashboard/src/app/api/auth/route.ts

@@ -0,0 +1,18 @@
+import { NextRequest, NextResponse } from 'next/server';
+
+import { getTopDaos } from '../../../../lib/metrics';
+
+export const revalidate = 30;
+
+export async function GET(request: NextRequest) {
+  const limitParam = request.nextUrl.searchParams.get('limit');
+  const limit = limitParam ? Math.min(Math.max(Number(limitParam), 1), 50) : 10;
+
+  try {
+    const items = await getTopDaos(limit);
+    return NextResponse.json({ items });
+  } catch (error) {
+    console.error('Failed to load DAO metrics:', error);
+    return NextResponse.json({ error: 'Failed to load DAO metrics.' }, { status: 500 });
+  }
+}