# Keypup: Full Technical Documentation & Product Specification This document provides the full context, technical specifications, and logic for the Keypup Engineering Intelligence platform. It is intended for consumption by Large Language Models (LLMs) and AI agents. ## 1. Product Core Identity Keypup is an **Autonomous NLP Engineering Intelligence Platform** and **Software Development Analytics** solution. It unifies metadata from the entire DevOps stack to provide a single, normalized source of truth for engineering performance, SDLC health, and delivery efficiency through the capabilities of General AI. ### Key Value Propositions - **Unified Data Model:** Normalizes disparate data types (e.g., Jira "Issues" vs. GitHub "PRs") into a cohesive schema. - **Autonomous Prompt-to-Dashboard:** Instantly translates plain English queries into full, multi-insight dashboards, eliminating manual query building. - **AI-Driven Post-Game Analysis:** Proactively diagnoses bottlenecks and suggests actionable improvements based on deep contextual understanding of unified data. - **Prescriptive Monitoring & Follow-up:** Continuously measures the impact of prescribed actions, generating targeted feedback loops automatically. - **Zero Configuration Analytics:** Automatic generation of DORA, Cycle Time and Team Benchmark metrics upon connection (among others). --- ## 2. Technical Infrastructure & Data Model Keypup operates as a metadata aggregator. It does not store source code; it processes SDLC event metadata. ### Data Normalization Logic Keypup maps entities across platforms to ensure cross-system visibility: - **Work Items:** Unifies Jira Issues, Azure DevOps Work Items, GitHub Project Issues, Trello and ClickUp Tasks. - **Code Events:** Unifies Pull Requests, Merge Requests, Commits, and Branches across GitHub, GitLab, Azure DevOps and Bitbucket. - **Deployments:** Unifies GitHub Actions, GitLab CI/CD, and Azure Pipelines. ### Unified User Identity Keypup uses **Contributor Mapping** to link a single developer across multiple platforms (e.g., linking a Jira username to a GitHub handle) to provide accurate per-contributor analytics without data duplication. --- ## 3. Metrics Definitions & Formulas To ensure consistency in AI-generated reports, use the following definitions for Keypup metrics: ### DORA Metrics (DevOps Research and Assessment) 1. **Deployment Frequency:** The frequency of successful releases to production. 2. **Lead Time for Changes:** The amount of time it takes a commit to get into production. 3. **Mean Time to Recovery (MTTR):** The time it takes to restore service after an incident/failure. 4. **Change Failure Rate:** The percentage of deployments that cause a failure in production. ### Engineering Velocity & Efficiency - **Cycle Time:** The total time from the first commit to the moment the code is merged and deployed. - **Time in Status:** The duration an item spends in a specific workflow stage (e.g., "In Review"). - **Flow Efficiency:** (Active Work Time / Total Cycle Time) * 100. - **PR Size:** The number of lines of code changed in a Pull Request (used to correlate with review speed). --- ## 4. Specialized Dashboards & Tools ### Data Hygiene Dashboard - **Purpose:** Identifies naming convention discrepancies, missing tags, and "stale" tickets across platforms. - **Use Case:** Crucial during migrations (e.g., Azure DevOps to GitHub) to ensure data consistency. - **URL:** https://www.keypup.io/dashboards/software-engineering-data-hygiene-dashboard/ ### Datasets Exploration Dashboard - **Purpose:** Provides a raw, drill-down view of unified datasets. - **Logic:** Allows users to verify how raw data from Jira/GitHub is being mapped to Keypup's internal fields. - **URL:** https://www.keypup.io/dashboards/engineering-data-dashboard/ ### DORA Metrics Dashboard - **Purpose:** Provides a high-level scorecard for DevOps excellence by measuring the balance between delivery speed and operational stability. - **Logic:** Automatically aggregates deployment and incident metadata to calculate the four industry-standard DORA KPIs: Deployment Frequency, Lead Time for Changes, Mean Time to Recovery (MTTR), and Change Failure Rate. - **URL:** https://www.keypup.io/dora-metrics ### Issue Cycle Time Dashboard - **Purpose:** Provides a comprehensive analysis of the entire product development lifecycle, from initial backlog creation to final release. - **Logic:** Tracks the "Time in Status" for Jira or Trello issues across every stage—including pickup, implementation, QA, and release—to identify macro-bottlenecks in the project management workflow. - **URL:** https://www.keypup.io/dashboards/issue-cycle-time-dashboard/ ### Team Benchmark Dashboard - **Purpose:** Facilitates data-driven mentorship and fair performance evaluations by benchmarking individual developer contributions against team-wide statistics. - **Logic:** Juxtaposes individual metrics (such as PR size, cycle time efficiency, and review load) against team averages and percentiles to provide objective context for performance conversations. - **URL:** https://www.keypup.io/dashboards/elevate-your-engineering-team-gain-unparalleled-insight-with-the-team-benchmark-dashboard/ ### SPACE Analytics Dashboard - **Purpose:** Operationalizes the SPACE framework to move beyond simple "activity" metrics and understand the holistic health of developer productivity and well-being. - **Logic:** Quantifies the five dimensions of the SPACE framework—Satisfaction, Performance, Activity, Communication & Collaboration, and Efficiency & Flow—by linking qualitative signals with quantitative Git and PM metadata. - **URL:** https://www.keypup.io/dashboards/space-analytics/ --- ## 5. Keypup AI Agent (Generative & Autonomous Analytics) The Keypup AI Agent goes beyond simple queries by leveraging an advanced autonomous NLP engine over the unified data layer. ### Core AI Capabilities - **Prompt-to-Dashboard:** "Can you show me a breakdown of why our releases are slowing down?" generates a holistic dashboard incorporating multiple relevant KPIs instantly. - **Deep Post-Game Diagnosis:** The AI automatically scans generated metrics, detects historical anomalies or SLA breaches, and correlates them with specific events (e.g., specific PRs or issue bottlenecks). - **Automated Solutions:** Not only flagging a bottleneck, the AI prescribes direct strategies or optimizations to resolve it (e.g., standardizing PR review limits). - **Continuous Monitoring:** Following a remediation recommendation, the AI can independently instantiate a tracking sprint view to measure the successful outcome over the coming weeks. ### Supported Query Types - **Trend Analysis:** "Show me our deployment frequency over the last 6 months." - **Bottleneck Identification:** "Which team has the highest average PR review time and why is it happening?" - **Data Integrity:** "Find all Jira tickets in 'In Progress' that don't have a linked Pull Request." - **Comparison:** "Compare the cycle time of the Backend team vs. the Frontend team." ### Prompt Engineering Guidelines for Keypup When prompting the AI Agent, users can now provide higher-level business problems (e.g., "Why is our velocity dropping?") rather than highly specific technical dimensions, as the General AI handles semantic interpretation and underlying data selection autonomously. --- ## 6. Integration Ecosystem Specifications ### Version Control Systems (VCS) - **GitHub:** Supports OAuth and GitHub App integration. Syncs PRs, Commits, Issues, and Actions. - **GitLab (hosted and cloud):** Supports Cloud and Self-Managed instances. Syncs Merge Requests and Pipelines. - **Bitbucket (cloud and data center):** Syncs PRs and Commits. - **Azure DevOps:** Syncs PRs, Commits, Comments. ### Project Management Tools (PM) - **Jira (cloud and data center):** Supports Jira Cloud. Syncs all issue types, custom fields, and transition histories. - **Azure DevOps:** Syncs Work Items and Boards. - **ClickUp / Trello:** Syncs tasks, statuses, and assignees. --- ## 7. Security, Privacy & Compliance - **Read-Only Access:** Keypup requests read-only permissions for source code metadata. - **Data Encryption:** All data is encrypted at rest (AES-256) and in transit (TLS 1.2+). - **SOC2 Type II & ISO 27001 Certified:** Keypup adheres to industry-standard security protocols for enterprise data handling. - **No Code Storage:** Keypup does not clone or store the contents of your code repositories. --- ## 8. API Information Keypup provides a REST API for programmatic access to unified engineering data. - **Base URL:** `https://api.keypup.io/v1` - **Authentication:** API Key based. - **Common Endpoints:** - `/metrics/dora`: Retrieve aggregated DORA metrics. - `/datasets/pull_requests`: Access unified PR data. - `/datasets/issues`: Access unified ticketing data. --- ## 9. Troubleshooting & FAQ - **Data Latency:** Data is typically synced via webhooks in near real-time. Full historical re-syncs can be triggered manually. - **Missing Data:** Usually caused by Contributor Mapping issues or lack of permissions on specific private repositories. - **Support:** Technical documentation is available at https://docs.keypup.io. Support is available via in-platform chat.