Skip to content
BranchesTags

Repository files navigation

Jira Flow Metrics Dashboard

A production-ready Next.js 14 dashboard for tracking Kanban team productivity using Jira Cloud API. Calculates throughput, cycle time metrics (average and p85), and breakdowns by assignee and issue type.

Features

  • 📊 Real-time Metrics: Throughput, average cycle time, and p85 cycle time
  • 📈 Historical Trends: View last 4 quarters of performance data
  • 👥 Team Breakdowns: See top assignees and issue type distributions
  • 🔄 Quarter Navigation: Easily switch between quarters
  • 📥 CSV Export: Download raw metrics for external analysis
  • ⚡ Optimized Performance: Server-side rendering with 1-hour caching
  • 📱 Responsive Design: Works on desktop, tablet, and mobile

Architecture

┌─────────────────────────────────────────┐
│   Next.js 14 App Router (TypeScript)    │
├─────────────────────────────────────────┤
│ app/                  - Server components│
│ components/           - Client & UI      │
│ lib/                  - Utilities        │
│   ├── env.ts          - Env validation   │
│   ├── jira.ts         - Jira API client  │
│   ├── types.ts        - TypeScript types │
│   └── utils.ts        - Helpers          │
├─────────────────────────────────────────┤
│  Jira Cloud API                         │
│  (Basic Auth, 1-hour cache)             │
└─────────────────────────────────────────┘

Tech Stack

  • Framework: Next.js 14 with App Router
  • Language: TypeScript (strict mode)
  • Styling: Tailwind CSS
  • Charts: Recharts
  • Dates: date-fns
  • UI Components: shadcn/ui + custom components
  • Deployment: Vercel

Quick Start

Prerequisites

  • Node.js 18+
  • pnpm 8+
  • Jira Cloud instance with API token

1. Clone and Install

git clone <repo>
cd jira-flow-metrics
pnpm install

2. Set Up Jira Credentials

Copy .env.example to .env.local:

cp .env.example .env.local

Fill in your Jira details:

JIRA_DOMAIN=your-domain.atlassian.net
JIRA_EMAIL=your-email@example.com
JIRA_TOKEN=your-jira-api-token
JIRA_PROJECT=YOUR_PROJECT_KEY
JIRA_DONE_STATUS=Done
JIRA_IN_PROGRESS_STATUS=In Progress

3. Get Your Jira API Token

  1. Go to Jira API Token Page
  2. Click "Create API token"
  3. Copy the token and paste it in .env.local

4. Find Your Jira Details

  • JIRA_DOMAIN: From your Jira URL (e.g., company.atlassian.net)
  • JIRA_PROJECT: Your project key (e.g., PROJ from PROJ-123)
  • JIRA_DONE_STATUS: Name of your "done" workflow status (e.g., Done, Closed)
  • JIRA_IN_PROGRESS_STATUS: Name of your "in progress" status (e.g., In Progress, Started)

5. Run Development Server

pnpm dev

Open http://localhost:3000 and you'll be redirected to /dashboard.

Environment Variables

Variable Required Description Example
JIRA_DOMAIN Yes Jira Cloud domain company.atlassian.net
JIRA_EMAIL Yes Email for API auth user@company.com
JIRA_TOKEN Yes Jira API token (from API token page)
JIRA_PROJECT Yes Project key MYPROJ
JIRA_DONE_STATUS Yes Status name for completed issues Done
JIRA_IN_PROGRESS_STATUS Yes Status name for in-progress issues In Progress

All variables are validated on app startup. Missing variables will throw a descriptive error.

Metrics Explained

Throughput

Number of issues completed in the quarter. Shows team velocity and capacity.

Average Cycle Time

Mean time from issue creation to resolution in days. Lower is better. Useful for understanding typical turnaround time.

P85 Cycle Time

85th percentile of cycle times. Shows the "upper bound" time for most issues. Important for SLA planning—50% of issues complete faster than this, 15% take longer.

By Assignee

Count of completed issues per team member. Identifies high-performers and workload distribution.

By Issue Type

Count of completed issues grouped by type (Story, Bug, Task, etc.). Highlights what the team is working on.

Features

Dashboard Page (/dashboard)

The main view displays:

  • Header: Current quarter and metadata
  • Controls: Quarter selector dropdown, CSV export button
  • KPI Cards: Throughput, Avg Cycle Time, P85 Cycle Time with QoQ deltas
  • Charts:
    • Throughput trend (last 4 quarters)
    • Cycle time trend (avg + p85 lines)
    • Top assignees (current quarter)
    • Issues by type (current quarter)
  • Raw Metrics Table: Quarterly summary table

Quarter Navigation

Click the quarter selector to view historical data. URL updates to ?quarter=2026Q3 and data refetches server-side.

CSV Export

Click "Export CSV" to download raw metrics for the selected quarter with columns:

  • Key, Summary, Type, Assignee, Created, Resolved, Cycle_Days

Error Handling

  • 401 Unauthorized: Invalid credentials (check email/token)
  • 400 Bad Request: Invalid project key or JQL (check JIRA_PROJECT and status names)
  • Network Error: Connection failed (check domain URL)
  • Missing Env Vars: App will not start without all required variables

Performance

  • Caching: All Jira API responses cached for 1 hour using Next.js revalidate: 3600
  • Parallel Fetching: Last 4 quarters fetched in parallel with Promise.all
  • Server Rendering: All metrics calculated server-side; charts render client-side
  • Optimized Bundles: Tailwind and Recharts tree-shaken automatically

Deployment to Vercel

1. Push to GitHub

git add .
git commit -m "Initial commit"
git push origin main

2. Connect to Vercel

  1. Go to Vercel Dashboard
  2. Import your GitHub repository
  3. Add environment variables (from .env.local)
  4. Click "Deploy"

3. Set Environment Variables

In Vercel Dashboard → Project Settings → Environment Variables, add:

JIRA_DOMAIN=...
JIRA_EMAIL=...
JIRA_TOKEN=...
JIRA_PROJECT=...
JIRA_DONE_STATUS=...
JIRA_IN_PROGRESS_STATUS=...

4. Done!

Your app is live and will auto-redeploy on main branch pushes.

Development

Project Structure

jira-flow-metrics/
├── app/
│   ├── layout.tsx              # Root layout with env validation
│   ├── page.tsx                # Redirect to /dashboard
│   ├── globals.css             # Tailwind + global styles
│   ├── dashboard/
│   │   ├── page.tsx            # Main dashboard (SSR)
│   │   ├── loading.tsx         # Loading skeleton
│   │   └── error.tsx           # Error boundary
│   └── api/
│       └── export/
│           └── route.ts        # CSV export endpoint
├── components/
│   ├── ui/                     # shadcn/ui base components
│   │   ├── card.tsx
│   │   ├── table.tsx
│   │   └── button.tsx
│   ├── kpi-card.tsx            # KPI metric card
│   ├── charts.tsx              # Recharts components
│   ├── quarter-selector.tsx    # Quarter dropdown
│   └── raw-metrics-table.tsx   # Metrics summary table
├── lib/
│   ├── env.ts                  # Environment validation
│   ├── jira.ts                 # Jira API client & calculations
│   ├── types.ts                # TypeScript interfaces
│   └── utils.ts                # Utility functions
├── package.json
├── tsconfig.json
├── tailwind.config.ts
├── postcss.config.js
├── next.config.js
├── .env.example
├── .gitignore
└── README.md

Key Functions

lib/jira.ts

  • getQuarterData(quarter: string): Fetch and calculate metrics for a single quarter
  • getMultipleQuartersData(quarters: string[]): Parallel fetch for multiple quarters
  • getQuarterDates(quarter: string): Parse quarter string to date range
  • percentile(arr: number[], p: number): Calculate p-th percentile
  • getCurrentQuarter(): Get current quarter in "YYYYQX" format

app/dashboard/page.tsx

  • Accepts ?quarter=2026Q3 URL param
  • Fetches last 4 quarters in parallel
  • Calculates QoQ deltas for KPI cards
  • Passes metrics to chart components

Adding New Metrics

To add a new metric (e.g., escaped issues):

  1. Add field to QuarterMetrics in lib/types.ts
  2. Implement calculation in getQuarterData() in lib/jira.ts
  3. Create new chart component or KPI card in components/
  4. Add to dashboard layout in app/dashboard/page.tsx

Troubleshooting

App won't start: Missing environment variables

Fix: Ensure all variables in .env.example are filled in .env.local.

cat .env.example  # Check required vars
cat .env.local    # Verify they're set
npm run dev       # Should work now

No data showing: Check Jira connection

Fix: Verify credentials and project key:

  1. Test domain: curl https://your-domain.atlassian.net/rest/api/3/myself -u email:token
  2. Verify status names: Go to Project Settings → Workflows → check exact status names
  3. Check logs: npm run dev output shows Jira errors

Charts not rendering

Fix: Open browser DevTools → Console. Look for Recharts errors. Ensure data is being fetched (check Network tab for /dashboard?quarter=...).

"P85 Cycle Time" higher than "Avg Cycle Time"

This is normal. P85 is the 85th percentile—by definition, 85% of issues have cycle times below this value. It's always >= average.

Contributing

This is a template for your team's use. To extend:

  1. Create feature branches: git checkout -b feat/new-metric
  2. Test locally: npm run dev
  3. Build for production: npm run build && npm run start
  4. Commit and push
  5. Deploy to Vercel

Performance Tips

  • Reduce cache time if metrics need real-time updates: Change revalidate: 3600 in lib/jira.ts
  • Filter by assignee: Add UI filter dropdown using getQuarterData() results
  • Add WIP chart: Track in-progress issues with similar Jira JQL
  • Pagination: For teams >200 issues/quarter, add pagination in makeJiraRequest()

License

MIT

Support

For issues or questions:

  1. Check Jira API docs: https://developer.atlassian.com/cloud/jira/rest/v3/
  2. Check Next.js docs: https://nextjs.org/docs
  3. Check error boundary: /dashboard error component shows detailed messages

Built with Next.js, Tailwind CSS, and Recharts. Deployed to Vercel.

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages