README.md

---
title: Enterprise Delivery & Workforce Intelligence API
emoji: 🚀
colorFrom: blue
colorTo: purple
sdk: docker
pinned: false
license: mit
---

# Enterprise Delivery & Workforce Intelligence API

## Overview
AI-powered enterprise intelligence system that converts raw engineering activity from Jira (and GitHub) into meaningful business-level insights. 

## Features

### 📊 Data Integration
- **Jira Integration**: Fetch issues, sprints, worklogs, team members, and project data
- **GitHub Integration**: (Coming soon - handled by frontend team)

### 🧠 Intelligence & Analytics
- **Delivery Health Metrics**: Track velocity, completion rates, cycle time, and sprint health
- **Productivity Metrics**: Monitor individual and team productivity, utilization, and efficiency
- **Cost Efficiency Analysis**: Calculate cost per feature, story point, and identify waste
- **Risk Alerts**: Automated detection of delivery delays, resource issues, and cost overruns
- **AI Insights**: Generate actionable recommendations based on engineering data

### 🎯 Business Impact
- Predict delivery delays early
- Optimize workforce allocation
- Identify cost inefficiencies
- Data-driven decision making for engineering leaders

## Project Structure

```
backend/
├── api/                      # FastAPI route handlers
│   ├── jira_routes.py       # Jira data endpoints
│   ├── intelligence_routes.py # Intelligence & metrics endpoints
│   └── __init__.py
├── config/                  # Configuration management
│   ├── settings.py         # Environment settings
│   └── __init__.py
├── integrations/           # External API integrations
│   ├── jira_service.py    # Jira API client
│   └── __init__.py
├── models/                 # Data models (Pydantic)
│   ├── jira_models.py     # Jira domain models
│   ├── intelligence_models.py # Intelligence metrics models
│   └── __init__.py
├── services/              # Business logic
│   ├── intelligence_service.py # Analytics & insights generation
│   └── __init__.py
├── main.py               # FastAPI application entry point
├── requirements.txt      # Python dependencies
├── .env.example         # Environment variables template
└── README.md           # This file
```

## Setup Instructions

### Prerequisites
- Python 3.9+
- Jira account with API access
- Jira API token ([Get it here](https://id.atlassian.com/manage-profile/security/api-tokens))

### Installation

1. **Clone the repository** (if not already done)
   ```bash
   cd d:\Datathon\backend
   ```

2. **Create virtual environment**
   ```bash
   python -m venv venv
   venv\Scripts\activate  # On Windows
   # source venv/bin/activate  # On Linux/Mac
   ```

3. **Install dependencies**
   ```bash
   pip install -r requirements.txt
   ```

4. **Configure environment variables**
   ```bash
   copy .env.example .env
   ```
   
   Edit `.env` with your credentials:
   ```env
   JIRA_SERVER_URL=https://your-domain.atlassian.net
   JIRA_EMAIL=your-email@example.com
   JIRA_API_TOKEN=your_jira_api_token
   SECRET_KEY=your-secret-key-here
   ```

5. **Run the application**
   ```bash
   python main.py
   ```
   
   Or using uvicorn directly:
   ```bash
   uvicorn main:app --reload --host 0.0.0.0 --port 8000
   ```

6. **Access the API**
   - API: http://localhost:8000
   - Interactive docs: http://localhost:8000/docs
   - Alternative docs: http://localhost:8000/redoc

## API Endpoints

### Jira Data Endpoints

#### Get All Projects
```http
GET /jira/projects
```

#### Get Project Issues
```http
GET /jira/projects/{project_key}/issues?start_date=2026-01-01&end_date=2026-02-07&max_results=100
```

#### Get Boards
```http
GET /jira/boards
```

#### Get Sprints for Board
```http
GET /jira/boards/{board_id}/sprints
```

#### Get Active Sprint
```http
GET /jira/boards/{board_id}/active-sprint
```

#### Get Sprint Issues
```http
GET /jira/sprints/{sprint_id}/issues
```

#### Get Team Members
```http
GET /jira/projects/{project_key}/team-members
```

#### Get Worklogs
```http
GET /jira/projects/{project_key}/worklogs?start_date=2026-01-01&end_date=2026-02-07
```

### Intelligence Endpoints

#### Get Delivery Health Metrics
```http
GET /intelligence/delivery-health/{project_key}?start_date=2026-01-01&end_date=2026-02-07
GET /intelligence/delivery-health/{project_key}?board_id=1&sprint_id=10
```

**Response:**
```json
{
  "sprint_name": "Sprint 1",
  "period_start": "2026-01-01",
  "period_end": "2026-02-07",
  "completed_story_points": 45.0,
  "velocity": 45.0,
  "completion_rate": 85.5,
  "avg_cycle_time_hours": 12.5,
  "health_score": 82.3,
  "blocked_issues_count": 2
}
```

#### Get Productivity Metrics
```http
GET /intelligence/productivity/{project_key}?start_date=2026-01-01&end_date=2026-02-07
```

**Response:**
```json
[
  {
    "team_member_name": "John Doe",
    "issues_completed": 8,
    "story_points_completed": 21.0,
    "total_hours_logged": 80.0,
    "productivity_score": 78.5,
    "utilization_rate": 90.0
  }
]
```

#### Get Cost Efficiency Metrics
```http
GET /intelligence/cost-efficiency/{project_key}?start_date=2026-01-01&avg_hourly_rate=75
```

**Response:**
```json
{
  "total_hours_logged": 320.0,
  "estimated_cost": 24000.0,
  "features_delivered": 15,
  "cost_per_feature": 1600.0,
  "cost_per_story_point": 533.33,
  "waste_percentage": 8.5
}
```

#### Get Risk Alerts
```http
GET /intelligence/risk-alerts/{project_key}?start_date=2026-01-01
```

**Response:**
```json
[
  {
    "alert_type": "delivery_delay",
    "severity": "high",
    "title": "Low Completion Rate",
    "description": "Only 45.0% of planned work is completed.",
    "suggested_action": "Reduce scope or extend timeline to meet commitments."
  }
]
```

#### Get AI Insights
```http
GET /intelligence/insights/{project_key}?start_date=2026-01-01
```

**Response:**
```json
[
  {
    "category": "delivery",
    "title": "Velocity Analysis",
    "description": "Team completed 45.0 story points with 85.5% completion rate.",
    "confidence_score": 0.85,
    "impact_level": "medium",
    "recommendations": [
      "Maintain current sprint planning strategy",
      "Consider increasing capacity for higher throughput"
    ]
  }
]
```

#### Get Complete Dashboard
```http
GET /intelligence/dashboard/{project_key}?start_date=2026-01-01&end_date=2026-02-07
```

**Response includes all metrics:**
- Delivery health
- Productivity metrics for all team members
- Cost efficiency
- Risk alerts
- AI insights

## Usage Examples

### Example 1: Monitor Sprint Health
```python
import requests

# Get active sprint
response = requests.get(
    "http://localhost:8000/jira/boards/1/active-sprint"
)
sprint = response.json()

# Get delivery health for that sprint
response = requests.get(
    f"http://localhost:8000/intelligence/delivery-health/PROJ",
    params={
        "board_id": 1,
        "sprint_id": sprint["sprint_id"]
    }
)
health = response.json()
print(f"Sprint Health Score: {health['health_score']}/100")
```

### Example 2: Team Productivity Report
```python
import requests

response = requests.get(
    "http://localhost:8000/intelligence/productivity/PROJ",
    params={
        "start_date": "2026-01-01",
        "end_date": "2026-02-07"
    }
)

for member in response.json():
    print(f"{member['team_member_name']}: {member['productivity_score']}/100")
```

### Example 3: Cost Analysis
```python
import requests

response = requests.get(
    "http://localhost:8000/intelligence/cost-efficiency/PROJ",
    params={
        "start_date": "2026-01-01",
        "avg_hourly_rate": 80
    }
)

cost = response.json()
print(f"Cost per Story Point: ${cost['cost_per_story_point']:.2f}")
print(f"Waste: {cost['waste_percentage']:.1f}%")
```

## Integration with Frontend

The frontend team working on GitHub integration can consume these endpoints:

1. **Dashboard View**: Use `/intelligence/dashboard/{project_key}` for comprehensive data
2. **Real-time Alerts**: Poll `/intelligence/risk-alerts/{project_key}` for updates
3. **Team Performance**: Display `/intelligence/productivity/{project_key}` data

## Future Enhancements

- [ ] GitHub integration for code metrics
- [ ] Real-time websocket updates
- [ ] Historical trend analysis
- [ ] Machine learning predictions
- [ ] Custom metric definitions
- [ ] Team capacity planning
- [ ] Automated reporting

## Troubleshooting

### Common Issues

**401 Unauthorized Error**
- Check Jira API token is valid
- Verify email and server URL in `.env`

**No data returned**
- Ensure project key is correct
- Check date ranges are valid
- Verify you have access to the Jira project

**Import errors**
- Activate virtual environment
- Run `pip install -r requirements.txt`

## Contributing

This is an MVP for a datathon. Focus areas:
1. Jira data accuracy
2. Intelligence algorithm improvements
3. API performance optimization

## License

MIT License - Datathon 2026

---

**Built for**: AI-Driven Enterprise Delivery & Workforce Intelligence
**Team**: Backend (Jira) + Frontend (GitHub)
**Date**: February 2026