startdata
/
jira-ai-fixer
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
jira-ai-fixer/docs/technical-en.md

595 lines
20 KiB
Markdown
Raw Blame History

# JIRA AI Fixer - Technical Document
**Version:** 1.1
**Date:** February 2026
**Classification:** Product Documentation
---
## 1. Overview
### 1.1 Objective
JIRA AI Fixer is an artificial intelligence system that integrates with JIRA and Bitbucket to automate Support Case analysis, identify affected modules in source code (COBOL/SQL/JCL), propose fixes, and automatically document solutions.
### 1.2 Scope
- **Languages:** COBOL, SQL, JCL (mainframe-focused)
- **Issues:** Support Cases in JIRA
- **Repositories:** Any Bitbucket Server repositories
- **Flexibility:** Configurable per client/product
### 1.3 High-Level Architecture
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ JIRA AI FIXER - ARCHITECTURE │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌───────────────┐ │
│ │ JIRA │ │
│ │ Server │ │
│ │ │ │
│ └───────┬───────┘ │
│ │ Webhook (issue_created, issue_updated) │
│ ▼ │
│ ┌───────────────────────────────────────────────────────────────────┐ │
│ │ EVENT PROCESSOR │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │
│ │ │ Queue │ │ Filter │ │ Issue Classifier │ │ │
│ │ │ (Redis) │──▶ (Support │──▶ (Product, Module, │ │ │
│ │ │ │ │ Cases) │ │ Severity) │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ │
│ └───────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌───────────────────────────────────────────────────────────────────┐ │
│ │ CODE INTELLIGENCE ENGINE │ │
│ │ │ │
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌──────────────┐ │ │
│ │ │ Bitbucket │ │ Code Index │ │ Context │ │ │
│ │ │ Connector │ │ (Embeddings) │ │ Builder │ │ │
│ │ │ │ │ │ │ │ │ │
│ │ │ │ │ - COBOL procs │ │ - CALLs │ │ │
│ │ │ │ │ - SQL tables │ │ - COPYBOOKs │ │ │
│ │ │ │ │ - JCL jobs │ │ - Includes │ │ │
│ │ └─────────────────┘ └─────────────────┘ └──────────────┘ │ │
│ │ │ │
│ │ Repositories: │ │
│ │ ├── Product-Base │ │
│ │ │ └── Product-Client-Fork │ │
│ │ │ └── Product-Client-AI (AI workspace) ← NEW │ │
│ └───────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌───────────────────────────────────────────────────────────────────┐ │
│ │ FIX GENERATION ENGINE │ │
│ │ │ │
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌──────────────┐ │ │
│ │ │ LLM Engine │ │ Fix Validator │ │ Output │ │ │
│ │ │ │ │ │ │ Generator │ │ │
│ │ │ - GPT-4o │ │ - Syntax check │ │ │ │ │
│ │ │ - Claude │ │ - COBOL rules │ │ - JIRA │ │ │
│ │ │ - Llama │ │ - SQL lint │ │ comment │ │ │
│ │ │ │ │ - JCL validate │ │ - PR/Branch │ │ │
│ │ └─────────────────┘ └─────────────────┘ └──────────────┘ │ │
│ └───────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌───────────────┴───────────────┐ │
│ ▼ ▼ │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ JIRA │ │ Bitbucket │ │
│ │ Comment │ │ Pull Request│ │
│ │ (Analysis + │ │ (AI Fork) │ │
│ │ Suggestion)│ │ │ │
│ └──────────────┘ └──────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
```
---
## 2. Detailed Components
### 2.1 Event Processor
#### 2.1.1 JIRA Webhook Receiver
```yaml
Endpoint: POST /api/webhook/jira
Events:
- jira:issue_created
- jira:issue_updated
Filters:
- issueType: "Support Case" (configurable)
- project: Configurable per installation
Authentication: Webhook Secret (HMAC-SHA256)
```
#### 2.1.2 Queue System
```yaml
Technology: Redis + Bull Queue
Queues:
- jira-events: Raw JIRA events
- analysis-jobs: Pending analysis jobs
- fix-generation: Fix generation tasks
Retry Policy:
- Max attempts: 3
- Backoff: exponential (1min, 5min, 15min)
Dead Letter Queue: jira-events-dlq
```
#### 2.1.3 Issue Classifier
Responsible for extracting metadata from issues:
```python
class IssueClassifier:
def classify(self, issue: JiraIssue) -> ClassifiedIssue:
return ClassifiedIssue(
product=self._detect_product(issue), # Configurable
module=self._detect_module(issue), # Authorization, Clearing, etc.
severity=self._detect_severity(issue), # P1, P2, P3
keywords=self._extract_keywords(issue), # Technical terms
stack_trace=self._parse_stack_trace(issue),
affected_programs=self._detect_programs(issue)
)
```
### 2.2 Code Intelligence Engine
#### 2.2.1 Bitbucket Connector
```yaml
Supported: Bitbucket Server (REST API 1.0)
Authentication: Personal Access Token or OAuth
Operations:
- Clone/Pull: Sparse checkout (relevant directories only)
- Read: Specific file contents
- Branches: Create/list branches in AI fork
- Pull Requests: Create PR from AI fork → client fork
```
**Access Structure per Repository:**
| Repository | AI Permission | Usage |
|------------|---------------|-------|
| Product-Base | READ | Reference, standards |
| Product-Client-Fork | READ | Current client code |
| Product-Client-AI | WRITE | AI branches and commits |
#### 2.2.2 Code Index (Embeddings)
**Embedding Providers (Configurable):**
| Provider | Use Case | Compliance |
|----------|----------|------------|
| Azure OpenAI | Enterprise (data stays in Azure) | High |
| OpenAI API | Standard deployments | Medium |
| Local (MiniLM) | Air-gapped / cost-sensitive | Maximum |
```yaml
Models:
- Azure: text-embedding-3-large (3072 dims)
- OpenAI: text-embedding-3-large (3072 dims)
- Local: all-MiniLM-L6-v2 (384 dims)
Vector DB: Qdrant (self-hosted)
Index separated by: product + client
```
**COBOL Code Indexing:**
```yaml
Granularity: By PROGRAM-ID / SECTION / PARAGRAPH
Extracted metadata:
- PROGRAM-ID
- COPY statements (dependencies)
- CALL statements (called programs)
- FILE-CONTROL (accessed files)
- SQL EXEC (tables/queries)
- Working Storage (main variables)
```
**SQL Indexing:**
```yaml
Granularity: By table/view/procedure
Extracted metadata:
- Object name
- Columns and types
- Foreign keys
- Referencing procedures
```
**JCL Indexing:**
```yaml
Granularity: By JOB / STEP
Extracted metadata:
- JOB name
- Executed PGMs
- DD statements (datasets)
- Passed PARMs
- Dependencies (JCL INCLUDEs)
```
#### 2.2.3 Context Builder
Assembles relevant context for LLM analysis:
```python
class ContextBuilder:
def build_context(self, issue: ClassifiedIssue) -> AnalysisContext:
# 1. Search programs mentioned in the issue
mentioned_programs = self._search_by_keywords(issue.keywords)
# 2. Search similar programs from past issues
similar_issues = self._find_similar_issues(issue)
# 3. Expand dependencies (COPYBOOKs, CALLs)
dependencies = self._expand_dependencies(mentioned_programs)
# 4. Get configured business rules
business_rules = self._get_business_rules(issue.product)
# 5. Build final context (respecting token limit)
return AnalysisContext(
primary_code=mentioned_programs[:5], # Max 5 main programs
dependencies=dependencies[:10], # Max 10 dependencies
similar_fixes=similar_issues[:3], # Max 3 examples
business_rules=business_rules,
total_tokens=self._count_tokens()
)
```
### 2.3 Fix Generation Engine
#### 2.3.1 LLM Engine
**Supported Providers:**
| Provider | Models | Use Case |
|----------|--------|----------|
| Azure OpenAI | GPT-4o, GPT-4 Turbo | Enterprise compliance |
| OpenAI | GPT-4o, GPT-4 Turbo | Standard deployment |
| OpenRouter | Llama 3.3, Claude, Mixtral | Cost-effective / free |
| Local | Ollama (Llama, CodeLlama) | Air-gapped |
```yaml
Configuration:
temperature: 0.2 # Low for code
max_tokens: 4096
top_p: 0.95
Gateway: LiteLLM (unified interface)
```
**COBOL Prompt Template:**
```
You are an expert in mainframe payment systems and COBOL programming.
## System Context
{business_rules}
## Reported Issue
{issue_description}
## Current Code
{code_context}
## Similar Fix History
{similar_fixes}
## Task
Analyze the issue and:
1. Identify the probable root cause
2. Locate the affected program(s)
3. Propose a specific fix
4. Explain the impact of the change
## Rules
- Maintain COBOL-85 compatibility
- Preserve existing copybook structure
- Do not change interfaces with other systems without explicit mention
- Document all proposed changes
## Response Format
{response_format}
```
#### 2.3.2 Fix Validator
**COBOL Validations:**
```yaml
Syntax:
- Compilation with GnuCOBOL (syntax check)
- Verification of referenced copybooks
Semantics:
- CALLs to existing programs
- Variables declared before use
- Compatible PIC clauses
Style:
- Standard indentation (Area A/B)
- Naming conventions
- Mandatory comments
```
**SQL Validations:**
```yaml
- Syntax check with SQL parser
- Verification of existing tables/columns
- Performance analysis (EXPLAIN)
```
**JCL Validations:**
```yaml
- JCL syntax check
- Referenced datasets exist
- Referenced PGMs exist
```
---
## 3. Repository Structure (AI Fork)
### 3.1 AI Fork Creation
```bash
# Proposed structure in Bitbucket
projects/
├── PRODUCT/
│ ├── Product-Base # Base product (existing)
│ ├── Product-Client-Fork # Client fork (existing)
│ └── Product-Client-AI # AI fork (NEW)
```
### 3.2 Branch Flow
```
Product-Client-Fork (client)
│
│ fork
▼
Product-Client-AI (AI workspace)
│
├── main (sync with client)
│
└── ai-fix/JIRA-1234-description
│
│ Pull Request
▼
Product-Client-Fork (client)
│
│ Review + Approve
▼
merge
```
### 3.3 Commit Convention
```
[AI-FIX] JIRA-1234: Short fix description
Problem:
- Original problem description
Solution:
- What was changed and why
Modified files:
- src/cobol/PROGRAM.CBL (lines 1234-1256)
Confidence: 85%
Generated by: JIRA AI Fixer v1.0
Co-authored-by: ai-fixer@company.com
```
### 3.4 Recommended Permissions
| User/Group | Base Product | Client Fork | AI Fork |
|------------|--------------|-------------|---------|
| ai-fixer-svc | READ | READ | WRITE |
| developers | WRITE | WRITE | READ |
| tech-leads | ADMIN | ADMIN | ADMIN |
---
## 4. Technology Stack
### 4.1 Backend
```yaml
Runtime: Python 3.11+
Framework: FastAPI
Async: asyncio + httpx
Queue: Redis 7+ with Bull Queue
Database: PostgreSQL 15+ (metadata, configurations, logs)
Vector DB: Qdrant 1.7+ (self-hosted)
Cache: Redis
```
### 4.2 Frontend (Admin Portal)
```yaml
Framework: React 18+
UI Kit: Tailwind CSS + shadcn/ui
State: React Query
Build: Vite
```
### 4.3 Infrastructure
```yaml
Container: Docker + Docker Compose
Orchestration: Docker Swarm or Kubernetes
CI/CD: Configurable (Bitbucket Pipelines, GitHub Actions, etc.)
Reverse Proxy: Traefik
SSL: Let's Encrypt
Monitoring: Prometheus + Grafana
Logs: ELK Stack or Loki
```
### 4.4 External Integrations
```yaml
LLM (Configurable):
- Azure OpenAI (enterprise)
- OpenAI API (standard)
- OpenRouter (cost-effective)
- Local Ollama (air-gapped)
Embeddings (Configurable):
- Azure OpenAI text-embedding-3-large
- OpenAI text-embedding-3-large
- Local MiniLM-L6-v2
JIRA:
API: REST API v2 (Server)
Auth: Personal Access Token
Bitbucket:
API: REST API 1.0 (Server)
Auth: Personal Access Token
```
---
## 5. Security
### 5.1 Sensitive Data
```yaml
Source code:
- Processed in memory, not persisted to disk
- Embeddings stored in Qdrant (encrypted at-rest)
- Sanitized logs (no complete code)
Credentials:
- Environment variables or secrets manager
- Automatic token rotation supported
- Access audit log
LLM and Embeddings:
- Configurable: Azure (compliance) or local (air-gapped)
- No data used for training when using Azure OpenAI
```
### 5.2 Network
```yaml
Deployment:
- Can be internal network only (not exposed to internet)
- HTTPS/TLS 1.3 communication
- Firewall: only JIRA and Bitbucket can access webhooks
Authentication:
- Admin Portal: Token-based or SSO integration
- API: JWT tokens with configurable expiration
- Webhooks: HMAC-SHA256 signature verification
```
### 5.3 Compliance Options
```yaml
Options:
- [ ] Data segregation by client/product
- [ ] Complete audit trail (who, when, what)
- [ ] Configurable log retention
- [ ] 100% on-premise deployment option
- [ ] Air-gapped deployment (local LLM + embeddings)
```
---
## 6. Deployment Options
### 6.1 SaaS (Hosted)
```yaml
Infrastructure: Managed by vendor
Updates: Automatic
Cost: Monthly subscription
Best for: Quick start, low maintenance
```
### 6.2 On-Premise
```yaml
Infrastructure: Customer's data center
Updates: Customer-controlled
Cost: License + internal infra
Best for: Compliance requirements, air-gapped
```
### 6.3 Hybrid
```yaml
Infrastructure: Customer hosts, vendor manages
Updates: Coordinated
Cost: License + reduced support
Best for: Balance of control and convenience
```
---
## 7. Estimates
### 7.1 Implementation Timeline
| Phase | Duration | Deliverables |
|-------|----------|--------------|
| **1. Initial Setup** | 1-2 weeks | Infra, repos, basic configuration |
| **2. Integration** | 1 week | JIRA webhook, Bitbucket connector |
| **3. Code Indexing** | 1-2 weeks | Repository indexing, embeddings |
| **4. Business Rules** | 1 week | Module configuration |
| **5. Testing** | 1 week | Validation with real issues |
| **Total** | **5-7 weeks** | |
### 7.2 Monthly Operational Costs (Estimate)
| Deployment | Infra | LLM APIs | Total |
|------------|-------|----------|-------|
| SaaS | Included | Included | $2,000-5,000/mo |
| On-Premise | Customer | ~$50-200/mo | License + infra |
| Air-gapped | Customer | $0 | License + infra |
---
## 8. Success Metrics
### 8.1 Technical KPIs
| Metric | MVP Target | 6-Month Target |
|--------|------------|----------------|
| Successful analysis rate | 80% | 95% |
| Accepted fixes (no modification) | 30% | 50% |
| Accepted fixes (with adjustments) | 50% | 70% |
| Average analysis time | < 5 min | < 2 min |
| System uptime | 95% | 99% |
### 8.2 Business KPIs
| Metric | Target |
|--------|--------|
| Initial analysis time reduction | 50% |
| Issues with useful suggestion | 70% |
| Team satisfaction | > 4/5 |
---
## 9. Getting Started
### 9.1 Prerequisites
- JIRA Server with webhook capability
- Bitbucket Server with API access
- Docker environment (SaaS) or Kubernetes (on-premise)
### 9.2 Quick Start
```bash
# Clone repository
git clone https://github.com/your-org/jira-ai-fixer.git
cd jira-ai-fixer
# Configure
cp .env.example .env
# Edit .env with your credentials
# Run
docker compose up -d
# Access portal
open https://localhost:8080
```
---
**JIRA AI Fixer - Intelligent Support Case Resolution**
*Contact: sales@yourcompany.com*
Reference in New Issue View Git Blame Copy Permalink