20 KiB
20 KiB
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
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
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:
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
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 |
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:
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:
Granularity: By table/view/procedure
Extracted metadata:
- Object name
- Columns and types
- Foreign keys
- Referencing procedures
JCL Indexing:
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:
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 |
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:
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:
- Syntax check with SQL parser
- Verification of existing tables/columns
- Performance analysis (EXPLAIN)
JCL Validations:
- JCL syntax check
- Referenced datasets exist
- Referenced PGMs exist
3. Repository Structure (AI Fork)
3.1 AI Fork Creation
# 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
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)
Framework: React 18+
UI Kit: Tailwind CSS + shadcn/ui
State: React Query
Build: Vite
4.3 Infrastructure
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
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
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
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
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)
Infrastructure: Managed by vendor
Updates: Automatic
Cost: Monthly subscription
Best for: Quick start, low maintenance
6.2 On-Premise
Infrastructure: Customer's data center
Updates: Customer-controlled
Cost: License + internal infra
Best for: Compliance requirements, air-gapped
6.3 Hybrid
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
# 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