Context Clues

Intelligent Context Automation for Jira Issues

Context Clues automatically generates contextual briefs when Jira issues move to "In Progress" by analyzing related work from both Jira and Notion, then using AI to create intelligent summaries that help developers understand the problem and find relevant resources.

🚀 Quick Start

1. Environment Setup

# Clone and install
git clone <repository-url>
cd context-clues
npm install

# Configure environment
cp env.template .env
# Edit .env with your credentials (see Environment Variables section below)

2. Notion OAuth Setup (Required for Enhanced Search)

# Start the server
npm start

# Visit the OAuth endpoint in your browser
open http://localhost:8080/auth/notion

# Complete the OAuth flow to authenticate with Notion
# Tokens will be automatically stored in ~/.mcp/notion_tokens.json

3. Start Development Server

npm run dev

4. Configure Jira Webhook

• Trigger: Issue → "In Progress"
• URL: https://<your-service>/jira/context-brief
• Headers: X-Auth-Shared-Secret: <your-secret>, Content-Type: application/json

📋 System Overview

graph TB
    subgraph "External Systems"
        JIRA[Jira Cloud]
        NOTION[Notion Workspace]
        OPENAI[OpenAI API]
    end
    
    subgraph "Context Clues Service"
        WEBHOOK[Webhook Endpoint]
        SEARCH[Search Engine]
        AI[AI Service]
        COMMENT[Comment Poster]
    end
    
    JIRA -->|Webhook| WEBHOOK
    WEBHOOK --> SEARCH
    SEARCH --> JIRA
    SEARCH --> NOTION
    SEARCH --> AI
    AI --> OPENAI
    AI --> COMMENT
    COMMENT --> JIRA

Loading

🏗️ Architecture

• Webhook Processing: Secure HMAC-verified webhook handling
• Intelligent Search: Parallel searches across Jira and Notion
• AI-Powered Briefs: GPT-4o-mini generates contextual summaries
• Secure Integration: Multi-layer security with rate limiting
• Cloud-Native: Deployed on Azure with Kubernetes support

📚 Documentation

Document	Description
📖 Architecture Guide	Complete system architecture and components
🔌 API Documentation	Detailed API endpoints and examples
🚀 Deployment Guide	Azure and Kubernetes deployment instructions
🔒 Security Documentation	Security architecture and best practices
🏗️ Infrastructure Guide	Azure infrastructure and Pulumi configuration
📊 Data Flow Guide	Complete data processing pipeline

🛠️ Development

Prerequisites

• Node.js: 18.x LTS or higher
• npm: 9.x or higher
• Docker: 20.x or higher (for containerization)
• Azure CLI: 2.50.0 or higher (for deployment)

Local Development

# Install dependencies
npm install

# Start development server
npm run dev

# Run tests
npm test

# Build for production
npm run build

Environment Variables

# Server Configuration
PORT=8080
NODE_ENV=development
SHARED_SECRET=your-random-secret-here

# Jira Configuration
JIRA_BASE=https://yourcompany.atlassian.net
[email protected]
JIRA_API_TOKEN=your-jira-api-token

# OpenAI Configuration
OPENAI_API_KEY=sk-your-openai-api-key

# Notion Configuration (Traditional API - Optional)
NOTION_TOKEN=secret_your-notion-token

# Notion MCP OAuth Configuration (Required for Enhanced Search)
# These are automatically configured during OAuth flow
NOTION_REDIRECT_URI=http://localhost:8080/callback
NOTION_MCP_URL=https://mcp.notion.com/mcp

🚀 Deployment

Azure App Service

# Deploy infrastructure
cd infrastructure
pulumi up

# Deploy application
az webapp deployment source config-zip \
  --resource-group context-clues-sandbox \
  --name context-clues-app-sandbox \
  --src app.zip

Kubernetes

# Build and push container
docker build -t contextcluesregistry.azurecr.io/context-clues:v1.0.0 .
docker push contextcluesregistry.azurecr.io/context-clues:v1.0.0

# Deploy to Kubernetes
kubectl apply -f k8s/

🔧 API Endpoints

Production Endpoints

• POST /jira/context-brief - Main webhook endpoint (HMAC secured)
• GET /health - Health check endpoint

OAuth Endpoints

• GET /auth/notion - Initiate Notion OAuth flow
• GET /callback - OAuth callback handler
• GET /auth/notion/status - Check OAuth authentication status

Testing Endpoints

• POST /test/brief - Simple brief generation
• POST /test/webhook - Full webhook simulation
• POST /jira/process - Process specific issue by key

🔒 Security Features

• HMAC-SHA256 Verification: Webhook signature validation
• Rate Limiting: 10 requests/minute per IP
• IP Validation: Source IP monitoring and logging
• Input Sanitization: XSS and injection prevention
• Secret Management: Azure Key Vault integration
• Encrypted Transit: HTTPS/TLS for all communications

📊 Monitoring

• Application Insights: Real-time performance monitoring
• Health Checks: Automated service health validation
• Structured Logging: Comprehensive request and error logging
• Alert System: Automated alerts for failures and performance issues

🧪 Testing

# Test webhook processing
curl -X POST http://localhost:8080/test/brief \
  -H "Content-Type: application/json" \
  -d '{"title": "Test Issue", "description": "Testing deployment"}'

# Test health endpoint
curl http://localhost:8080/health

# Test specific issue processing
curl -X POST http://localhost:8080/jira/process \
  -H "Content-Type: application/json" \
  -d '{"key": "PROJECT-123"}'

📈 Performance

• Parallel Processing: Concurrent Jira and Notion searches
• Horizontal Scaling: Kubernetes auto-scaling (2-10 replicas)
• Caching: In-memory result caching for similar queries
• Optimized Queries: Efficient JQL and Notion search queries

🛡️ Security Best Practices

• Least Privilege: Minimal required permissions
• Secret Rotation: Regular credential updates
• Audit Logging: Complete request audit trail
• Network Security: VNet integration and private endpoints
• Compliance: SOC 2, ISO 27001, GDPR compliance

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👥 Support

• Documentation: Check the docs/ directory for detailed guides
• Issues: Report bugs and feature requests via GitHub Issues
• Security: Report security issues privately to the maintainers

🏷️ Tags

jira notion automation context ai webhook azure kubernetes nodejs openai