{"id":51086461,"url":"https://github.com/kingztech2019/cadence-plane-analytics","last_synced_at":"2026-06-23T22:04:15.250Z","repository":{"id":364882501,"uuid":"1268393122","full_name":"kingztech2019/cadence-plane-analytics","owner":"kingztech2019","description":"Delivery analytics for Plane — cycle time, bottleneck tracking, team health, and Monte Carlo forecasts. Open source.","archived":false,"fork":false,"pushed_at":"2026-06-14T22:35:55.000Z","size":2390,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-15T00:18:31.345Z","etag":null,"topics":["analytics","cycle-time","devops","engineering-metrics","nextjs","open-source","open-source-project","plane","typescript"],"latest_commit_sha":null,"homepage":"https://cadence-plane-analytics.netlify.app/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kingztech2019.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-13T13:31:38.000Z","updated_at":"2026-06-14T22:35:59.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/kingztech2019/cadence-plane-analytics","commit_stats":null,"previous_names":["kingztech2019/cadence-plane-analytics"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/kingztech2019/cadence-plane-analytics","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kingztech2019%2Fcadence-plane-analytics","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kingztech2019%2Fcadence-plane-analytics/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kingztech2019%2Fcadence-plane-analytics/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kingztech2019%2Fcadence-plane-analytics/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kingztech2019","download_url":"https://codeload.github.com/kingztech2019/cadence-plane-analytics/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kingztech2019%2Fcadence-plane-analytics/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34708299,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-23T02:00:07.161Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["analytics","cycle-time","devops","engineering-metrics","nextjs","open-source","open-source-project","plane","typescript"],"created_at":"2026-06-23T22:04:14.361Z","updated_at":"2026-06-23T22:04:15.234Z","avatar_url":"https://github.com/kingztech2019.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"docs/logo.png\" alt=\"Cadence\" width=\"72\" /\u003e\n\n# Cadence\n\n**Delivery analytics for [Plane](https://plane.so) — understand how your team actually ships software**\n\n[![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](LICENSE)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6?logo=typescript\u0026logoColor=white)](https://www.typescriptlang.org/)\n[![Next.js](https://img.shields.io/badge/Next.js-15-black?logo=next.js)](https://nextjs.org/)\n[![Fastify](https://img.shields.io/badge/Fastify-5.x-000000?logo=fastify)](https://fastify.dev/)\n[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-16-336791?logo=postgresql\u0026logoColor=white)](https://www.postgresql.org/)\n[![Docker](https://img.shields.io/badge/Docker-ready-2496ED?logo=docker\u0026logoColor=white)](https://www.docker.com/)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)\n\n[Features](#features) · [Screenshots](#screenshots) · [Quick Start](#quick-start) · [Configuration](#configuration) · [Contributing](#contributing)\n\n---\n\n![Cadence — Cycle Time with Project Pulse strip](docs/screenshots/hero.png)\n\n\u003c/div\u003e\n\n## What is Cadence?\n\nPlane gives you project management. Cadence gives you the engineering metrics that answer *why* work is fast or slow.\n\nIt connects to any Plane workspace (cloud or self-hosted) via API key or OAuth, continuously syncs your issues and state-transition history, and surfaces actionable analytics that Plane's built-in dashboards don't provide:\n\n- **How long does work actually take?** Cycle time and lead time, not just status counts.\n- **Where do issues get stuck?** The bottleneck isn't always obvious from a board view.\n- **Who is overloaded, and who is struggling?** Per-person health flags before burnout happens.\n- **Will we hit our deadline?** Monte Carlo simulation over your real throughput history.\n\n\u003e **No write access required.** Cadence only reads from Plane. It never modifies issues, comments, or state.\n\n---\n\n## Features\n\n### Metrics\n| Feature | Description |\n|---|---|\n| **Cycle Time** | Scatter chart + P50/P85 stats + trend vs prior 30 days |\n| **Lead Time** | Created → Done distribution with percentile benchmarks |\n| **Bottleneck Tracker** | Which stage delays work most, with persistence across 30-day windows |\n| **WIP / CFD** | Cumulative Flow Diagram showing work-in-progress balance over time |\n| **Throughput** | Issues completed per person + team health flags (overloaded, slow, high reactivation) |\n| **Sprint Comparison** | Sprint-over-sprint velocity, P50/P85, and scope creep |\n| **Flow Efficiency** | Active vs waiting time ratio benchmarked against industry norms |\n| **Scope Creep** | Per-sprint added work vs committed work |\n| **Monte Carlo Forecast** | Probabilistic delivery date from real historical throughput |\n| **At-Risk Radar** | Issues currently in-progress that have already exceeded their state P85 |\n\n### Insights\n| Feature | Description |\n|---|---|\n| **Project Pulse** | One-line signal strip above every page — surfaces critical issues, trend changes, and persistent bottlenecks |\n| **Flow Health Score** | A/B/C/D/F composite score from cycle time trend, WIP balance, reactivation rate, and throughput trend |\n| **Bottleneck Recommendations** | 3 targeted, category-aware action items per bottleneck, escalating to \"Urgent\" after 3+ consecutive periods |\n| **AI Sprint Retrospective** | OpenRouter-powered narrative summary comparing sprint performance to the prior sprint |\n\n### Platform\n| Feature | Description |\n|---|---|\n| **Shareable dashboards** | One-click read-only link — no login required for recipients |\n| **Issue journey drill-through** | Click any issue to see its full state timeline |\n| **Cross-project contributors** | Workspace-level view of each member's output across all projects |\n| **Filter bar** | Filter every metric by sprint, assignee, priority, label, and date range |\n| **State mapping** | Override Plane's flow categories per project (e.g. mark \"QA\" as `review`) |\n\n---\n\n## Screenshots\n\n### Dashboard\n\u003e Overview of all tracked projects with live sync status. Each card shows quick links to Delivery Speed, Bottlenecks, Work Flow, and Team Output for that project.\n\n![Dashboard](docs/screenshots/dashboard.png)\n\n---\n\n### Project Pulse + Cycle Time\n\u003e The Pulse strip surfaces your top signals on every page — bottleneck alerts, at-risk count, and trend changes. Cycle Time shows a scatter distribution with P50/P85 reference lines and a trend comparison vs the prior 30 days.\n\n![Cycle Time page](docs/screenshots/cycle-time.png)\n\n---\n\n### Lead Time\n\u003e How long from ticket created to ticket done — including all the waiting time, not just active development. Shows P50, P85, and a per-issue breakdown table.\n\n![Lead Time page](docs/screenshots/lead-time.png)\n\n---\n\n### Bottleneck Tracker\n\u003e Identifies the stage where issues spend the most time. Tracks persistence across consecutive 30-day windows and escalates to \"Critical\" messaging when the same stage has been the bottleneck for 3+ periods — with targeted action recommendations.\n\n![Bottleneck page](docs/screenshots/bottleneck.png)\n\n---\n\n### WIP / Cumulative Flow Diagram\n\u003e Watch work pile up (or flow smoothly) through each stage over time. A growing band in any one stage signals a bottleneck forming.\n\n![CFD page](docs/screenshots/cfd.png)\n\n---\n\n### Team Health \u0026 Throughput\n\u003e Per-person completion counts and typical cycle time. The Team Health Flags section surfaces overloaded members (high WIP), slow outliers (P85 \u003e 1.5× team average), and high reactivation rates before they become a problem.\n\n![Throughput page](docs/screenshots/throughput.png)\n\n---\n\n### Team Contributions\n\u003e Workspace-level view of each member's output across all projects — total issues completed, P50/P85 speed, and which projects they're contributing to.\n\n![Team contributions](docs/screenshots/team.png)\n\n---\n\n### Sprint Comparison\n\u003e Sprint-over-sprint velocity chart comparing completed issues, P50/P85 cycle time, and scope added per sprint. The AI Retrospective button generates a narrative summary powered by OpenRouter.\n\n![Sprints page](docs/screenshots/sprints.png)\n\n---\n\n### Flow Efficiency\n\u003e Ratio of active working time to total lead time, benchmarked against the industry median of ~15%. Includes a distribution histogram and a per-issue breakdown sorted by efficiency.\n\n![Flow Efficiency page](docs/screenshots/flow-efficiency.png)\n\n---\n\n### Scope Creep\n\u003e How much work gets added mid-sprint vs committed at the start. Sprints above the 30% danger threshold are highlighted — a leading indicator of missed goals.\n\n![Scope Creep page](docs/screenshots/scope-creep.png)\n\n---\n\n### At-Risk Radar\n\u003e Issues currently in-progress that have already exceeded their state's P85. Sorted by overage percentage so you know exactly which issues need attention right now.\n\n![At-Risk page](docs/screenshots/at-risk.png)\n\n---\n\n### Monte Carlo Forecast\n\u003e Probabilistic delivery estimation using 10,000 simulations over your team's real weekly throughput. Returns P50, P85, and P95 completion dates for a given backlog size.\n\n![Forecast page](docs/screenshots/forecast.png)\n\n---\n\n## Tech Stack\n\n| Layer | Technology |\n|---|---|\n| **Monorepo** | [Turborepo](https://turbo.build/) |\n| **Frontend** | [Next.js 15](https://nextjs.org/) (App Router) · [Tailwind CSS v4](https://tailwindcss.com/) · [Recharts](https://recharts.org/) |\n| **Backend** | [Fastify 5](https://fastify.dev/) · [Node.js 22](https://nodejs.org/) |\n| **Database** | [PostgreSQL 16](https://www.postgresql.org/) — `PERCENTILE_CONT`, window functions, generated columns |\n| **Queue** | [BullMQ](https://bullmq.io/) + [Redis 7](https://redis.io/) — rate-limited backfill workers |\n| **Auth** | JWT (tool accounts) + OAuth 2.0 PKCE (Plane marketplace) |\n| **AI** | [OpenRouter](https://openrouter.ai/) — sprint retrospective narratives (optional) |\n| **Infra** | Docker Compose · designed for Vercel (web) + VPS (API/workers) |\n\n---\n\n## Quick Start\n\n### Prerequisites\n\n- [Docker](https://docs.docker.com/get-docker/) and [Docker Compose](https://docs.docker.com/compose/install/)\n- A Plane workspace (cloud at [app.plane.so](https://app.plane.so) or self-hosted)\n- A Plane API token: **Profile → API tokens → Create token**\n\n### 1. Clone the repository\n\n```bash\ngit clone https://github.com/kingztech2019/cadence-plane-analytics.git\ncd cadence-plane-analytics\n```\n\n### 2. Configure environment\n\n```bash\ncp .env.example .env\n```\n\nOpen `.env` and set at minimum:\n\n```env\nPOSTGRES_PASSWORD=choose_a_strong_password\nJWT_SECRET=choose_a_long_random_secret\nENCRYPTION_KEY=32_byte_hex_string_for_aes256\n```\n\nGenerate the values quickly:\n\n```bash\n# JWT_SECRET\nnode -e \"console.log(require('crypto').randomBytes(48).toString('hex'))\"\n\n# ENCRYPTION_KEY (exactly 32 bytes → 64 hex chars)\nnode -e \"console.log(require('crypto').randomBytes(32).toString('hex'))\"\n```\n\n### 3. Start\n\n```bash\ndocker compose up -d\n```\n\nThis starts PostgreSQL, Redis, runs database migrations, starts the API on **port 4001**, and serves the web app on **port 3001**.\n\n### 4. Create your account\n\nOpen [http://localhost:3001](http://localhost:3001) and sign up. Then go to **Connections** and paste your Plane workspace URL (e.g. `https://app.plane.so/my-workspace/`) along with your API token.\n\nCadence will begin syncing in the background. Recent data (last 90 days) is ready in ~5 minutes; full history in ~30–60 minutes depending on workspace size.\n\n---\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Required | Description |\n|---|---|---|\n| `POSTGRES_PASSWORD` | Yes | PostgreSQL password |\n| `JWT_SECRET` | Yes | Secret for signing JWTs (min 32 chars) |\n| `ENCRYPTION_KEY` | Yes | 32-byte hex key for encrypting API tokens at rest |\n| `PLANE_CLIENT_ID` | OAuth only | App client ID from Plane workspace settings |\n| `PLANE_CLIENT_SECRET` | OAuth only | App client secret |\n| `PLANE_WEBHOOK_SECRET` | Optional | HMAC-SHA256 secret for real-time webhook updates |\n| `OAUTH_REDIRECT_URI` | OAuth only | Callback URL (default: `http://localhost:4001/api/auth/plane/callback`) |\n| `FRONTEND_URL` | Optional | Web app URL (default: `http://localhost:3000`) |\n| `OPENROUTER_API_KEY` | Optional | Enables AI Sprint Retrospective (uses `claude-3.5-haiku`) |\n\n### Connecting Plane\n\n**API Key (recommended for self-hosted):**\n1. In Plane: **Profile → API tokens → Create token**\n2. In Cadence: **Connections → paste workspace URL + token → Connect**\n\n**OAuth (for Plane marketplace listing):**\n1. Register your app in Plane: **Workspace Settings → Integrations → New app**\n2. Set `PLANE_CLIENT_ID`, `PLANE_CLIENT_SECRET`, and `OAUTH_REDIRECT_URI` in `.env`\n3. In Cadence: **Connections → OAuth tab → Continue with Plane**\n\n### State Mapping\n\nCadence groups Plane states into flow categories (`backlog`, `todo`, `in_progress`, `review`, `done`, `cancelled`) to compute metrics correctly. After connecting, go to **State Mapping** to review and adjust the automatic classification for each project.\n\n---\n\n## Development Setup\n\nFor local development without Docker:\n\n### Prerequisites\n- Node.js 22+\n- PostgreSQL 16+\n- Redis 7+\n\n### Install dependencies\n\n```bash\nnpm install\n```\n\n### Configure database\n\n```bash\n# Start Postgres and Redis locally, then:\ncp .env.example .env\n# Edit .env with your local connection strings\n```\n\n```env\nDATABASE_URL=postgres://postgres:password@localhost:5432/flow_analytics\nREDIS_URL=redis://localhost:6379\n```\n\n### Run migrations\n\n```bash\nnpx tsx apps/api/src/db/migrate.ts\n```\n\n### Start development servers\n\n```bash\nnpm run dev\n```\n\nThis starts the API on `:4001` and the web app on `:3000` simultaneously via Turborepo.\n\n### Build shared package\n\nWhen modifying types in `packages/shared/src/types/`, rebuild it:\n\n```bash\nnpx turbo run build --filter=@flow-analytics/shared\n```\n\n---\n\n## Architecture\n\n```\ncadence/\n├── apps/\n│   ├── api/                   # Fastify REST API + BullMQ workers\n│   │   ├── src/\n│   │   │   ├── routes/        # HTTP endpoints (auth, analytics, workspaces, shares)\n│   │   │   ├── services/\n│   │   │   │   ├── metricsService.ts   # All SQL queries — cycle time, lead time, CFD, ...\n│   │   │   │   ├── planeClient.ts      # Rate-limited Plane API client (60 req/min token bucket)\n│   │   │   │   ├── syncService.ts      # Orchestrates backfill + incremental sync\n│   │   │   │   └── aiService.ts        # OpenRouter wrapper for sprint retrospectives\n│   │   │   ├── workers/       # BullMQ: backfill (high/low priority), incremental, metrics\n│   │   │   └── db/            # Migrations + schema\n│   │   └── Dockerfile\n│   └── web/                   # Next.js 15 App Router\n│       ├── src/app/\n│       │   ├── (app)/         # Authenticated pages\n│       │   │   ├── projects/[projectId]/   # All analytics tabs\n│       │   │   └── dashboard/, connect/, setup/\n│       │   └── share/[token]/ # Public read-only dashboard\n│       └── Dockerfile\n└── packages/\n    └── shared/                # TypeScript types shared by API + web\n```\n\n### Data flow\n\n```\nPlane API  ──▶  BullMQ workers  ──▶  PostgreSQL\n                  (rate-limited                │\n                   60 req/min)                 │\n                                               ▼\nWebhook  ──────────────────────────▶  metricsService\n(real-time)                                    │\n                                               ▼\n                                         Fastify API\n                                               │\n                                               ▼\n                                         Next.js web\n```\n\n### Sync strategy\n\n- **Backfill**: Two-priority queue — `high` (issues updated in last 90 days, ~5 min) before `low` (full history, ~30-60 min). The user sees charts while the deep history is still processing.\n- **Incremental**: Polls Plane every 30 minutes for `updated_at \u003e last_cursor` changes.\n- **Webhooks**: Optional real-time updates via `X-Plane-Signature` HMAC-SHA256 verification.\n\n---\n\n## Roadmap\n\n- [ ] **Multi-workspace view** — compare metrics across workspaces side by side\n- [ ] **Custom dashboards** — pin and arrange any charts in a personal layout\n- [ ] **Slack / Teams notifications** — alert on new at-risk issues or bottleneck escalations\n- [ ] **CSV + PDF export** — for stakeholder reports\n- [ ] **Label and epic analytics** — breakdown by work type, not just state\n- [ ] **SLA tracking** — define time targets per issue type and track violations\n- [ ] **Plane marketplace listing** — one-click install from the Plane integrations gallery\n\nHave a feature in mind? [Open a discussion](https://github.com/kingztech2019/cadence-plane-analytics/discussions) or [submit a feature request](https://github.com/kingztech2019/cadence-plane-analytics/issues/new?template=feature_request.md).\n\n---\n\n## Contributing\n\nContributions are welcome and appreciated. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide.\n\n**Quick version:**\n1. Fork the repository\n2. Create a branch: `git checkout -b feat/your-feature`\n3. Make your changes and add tests where relevant\n4. Run `npm run typecheck` and `npm run lint` — both must pass\n5. Open a pull request with a clear description\n\nFor significant changes, please open an issue first to discuss the approach.\n\n---\n\n## Self-Hosting in Production\n\nThe Docker Compose setup works well for small-to-medium teams. For larger deployments:\n\n| Component | Recommended service |\n|---|---|\n| **Web** | [Vercel](https://vercel.com) (zero-config Next.js deploys) |\n| **API + Workers** | Any VPS with Docker (Hetzner, DigitalOcean, Fly.io) |\n| **PostgreSQL** | [Supabase](https://supabase.com), [Neon](https://neon.tech), or managed Postgres |\n| **Redis** | [Upstash](https://upstash.com) (serverless) or self-hosted |\n\nThe API and worker processes share the same Docker image — the worker is started with `node apps/api/dist/workers/start.js` instead of the default API entrypoint.\n\n---\n\n## Security\n\n- API tokens are encrypted at rest using AES-256-GCM before being stored in PostgreSQL.\n- Webhook payloads are verified with `crypto.timingSafeEqual` against the HMAC-SHA256 signature.\n- Shareable dashboard links use 16-byte random hex tokens — they cannot be enumerated.\n- Cadence requests **read-only** Plane scopes only. It never writes to your workspace.\n\nTo report a security vulnerability, please email **security@kingztech2019** rather than opening a public issue.\n\n---\n\n## License\n\nCadence is released under the [GNU AGPL-3.0 License](LICENSE).\n\n```\nAGPL-3.0 — Copyright (c) 2025 Cadence Contributors\n```\n\nYou are free to use, modify, and distribute this software for any purpose. See [LICENSE](LICENSE) for the full text.\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\nBuilt with care for engineering teams who want to understand — and improve — how they deliver software.\n\n**[⭐ Star this repo](https://github.com/kingztech2019/cadence-plane-analytics)** if Cadence is useful to you.\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkingztech2019%2Fcadence-plane-analytics","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkingztech2019%2Fcadence-plane-analytics","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkingztech2019%2Fcadence-plane-analytics/lists"}