# 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*