DevPulse — Developer Dashboard Project Overview

1. Executive Summary & Problem Solved

DevPulse is an interactive developer dashboard that consolidates four critical daily workflows into a single pane of glass:

Feature	Description
PR Review Tracking	Fetches, filters, and displays GitHub pull requests with review status, branch info, and assignee data via GitHub REST/GraphQL API integration.
CI/CD Pipeline Monitoring	Connects to CI/CD webhooks (GitHub Actions, generic webhook endpoints) to surface deployment pipeline status, build logs, and deployment history.
Code Snippet Manager	CRUD interface for storing, tagging, and searching reusable code snippets with syntax-highlighted previews.
Daily Changelog Generation	Scheduled automation that aggregates merged PRs, closed issues, and deployment events into a formatted daily changelog (markdown/HTML).

Problem Solved: Developers and tech leads lose context switching between GitHub, CI/CD tools, documentation repos, and snippet managers. DevPulse eliminates tab fatigue by providing a unified, real-time dashboard that surfaces actionable development intelligence in one view.

Key Scope Boundaries (MVP):

• Client-side caching only (no server-side Redis/Memcached)
• No Docker Compose or Kubernetes orchestration — local dev runs directly via npm scripts
• Single-tenant per deployment instance
• GitHub as the sole VCS provider (no GitLab/Bitbucket support in MVP)

---

2. Target Users & Value Proposition

Primary Users

Persona	Pain Point	DevPulse Value
Frontend Developer	Manually checking PRs across multiple repos	Consolidated PR feed with filter by repo, status, reviewer
Tech Lead	Tracking team velocity, deployment frequency	Dashboard overview of merged PRs, deployment counts, changelog auto-generation
DevOps Engineer	Monitoring multiple CI/CD pipelines across services	Webhook-driven pipeline status panel with build/logs access
Full-Stack Developer	Losing code snippets across files and tools	Searchable, tagged snippet library with copy-to-clipboard

Value Proposition

• Reduce context switching — All dev signals in one tab
• Automate documentation — Daily changelog generated without manual effort
• Accelerate onboarding — New team members browse snippets and pipeline history
• Zero-config auth — GitHub OAuth login via Better Auth with no custom token management

---

3. Tech Stack & Architectural Decisions (Rationale for choices)

Stack Overview

┌─────────────────────────────────────────────────────┐
│                   Client Layer                       │
│  Next.js 16 (App Router) + Tailwind CSS v4          │
├─────────────────────────────────────────────────────┤
│                   Auth Layer                         │
│  Better Auth (GitHub OAuth + session management)     │
├─────────────────────────────────────────────────────┤
│                   API Layer                          │
│  Express 5 (Webhook receivers, GitHub API proxy,     │
│             CI/CD status endpoints)                  │
├─────────────────────────────────────────────────────┤
│                   Data Layer                         │
│  Native MongoDB Driver (direct BSON interaction,     │
│             no ODM/ORM overhead)                     │
└─────────────────────────────────────────────────────┘

Decision Rationale

Technology	Why This Choice	What We Avoided	Rationale
Next.js 16	App Router provides file-based routing, server components for data fetching, and built-in API routes that co-locate frontend and backend logic.	Remix (steeper learning curve for MVP), Vite-only SPA (loses SSR benefits for SEO of changelog pages).	Next.js 16's server components reduce client-side JS bundle — critical for a dashboard that renders data tables.
Tailwind CSS v4	Utility-first approach enables rapid UI prototyping for dashboard components (tables, cards, status badges) without writing custom CSS.	MUI (heavy, opinionated components), plain CSS (slow for dashboard iteration).	Tailwind's @apply and v4's CSS-first config reduce config overhead. JIT engine keeps bundle small.
Better Auth	Purpose-built for Next.js; provides GitHub OAuth out of the box, session management, and middleware integration with zero boilerplate.	NextAuth.js (more configuration overhead, less type-safe), custom JWT solution (security risk, more code to maintain).	Better Auth's API-first design means auth state is available in both server components and API routes seamlessly.
Express 5	Lightweight, minimal framework for handling incoming webhooks (GitHub PR events, CI/CD status hooks) and proxying requests to GitHub's API.	NestJS (overkill for MVP, too much decorator/config), Fastify (less ecosystem support for webhook middleware).	Express 5's simplified middleware signature and improved router matching are ideal for webhook endpoint routing.
Native MongoDB Driver	Direct driver access eliminates ORM abstraction leaks, gives full control over queries, and is sufficient for the document-oriented data model (PRs, snippets, pipeline records, changelogs).	Mongoose (schema validation overhead, migration pain for MVP), Prisma (doesn't support MongoDB well in v1+).	For low-complexity MVP with known schemas, native driver with lightweight validation (Zod) at the application layer is faster and more transparent.

Architecture Diagram

GitHub ──webhooks──▶ Express 5 API Server ──▶ MongoDB
  │                     │
  │                     │── Better Auth (session/cookie)
  │                     │
  ▼                     ▼
Developer ──▶ Next.js 16 App ──reads from──▶ Express API (server actions)
  Browser     (Server Components)            (fetches from MongoDB)
                                         
Cron Job ──▶ Changelog Generator ──▶ GitHub API ──▶ Stored in MongoDB
(dayly)        (Node script / route)    (merged PRs)  (changelog collection)

Data Flow:

1. GitHub Webhooks → Express 5 receives pull_request, push, check_run events → validates signature → stores/updates MongoDB documents
2. Dashboard Reads → Next.js Server Components call Express API routes (same origin) → query MongoDB → return JSON to client
3. Auth Flow → Better Auth middleware handles GitHub OAuth callback → stores session → Express/Next.js middleware validates session on protected routes
4. Changelog Generation → Scheduled cron (node-cron or Vercel Cron) triggers Express endpoint → queries MongoDB for last 24h events → formats markdown → stores in changelogs collection

---

4. Repository Quickstart & Environment Setup

Repository Structure

devpulse/
├── app/                          # Next.js App Router (pages, layouts, server actions)
│   ├── (dashboard)/
│   │   ├── prs/
│   │   ├── pipelines/
│   │   ├── snippets/
│   │   └── changelog/
│   ├── api/                      # Next.js API routes (lightweight, delegates to Express)
│   ├── layout.tsx
│   └── page.tsx                  # Landing/redirect
├── server/                       # Express 5 API server
│   ├── index.ts                  # Express app entry
│   ├── routes/
│   │