16 KiB
16 KiB
JIRA AI Fixer - Architecture Document
System Overview
JIRA AI Fixer is a microservice that provides AI-powered issue analysis and automated fix generation for enterprise issue tracking systems.
High-Level Architecture
┌─────────────────────────────────────────────────────────────────────────────────┐
│ External Systems │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────┐ ┌─────────┐ ┌───────────┐ ┌─────────┐ ┌───────────┐ ┌─────────┐ │
│ │ JIRA │ │ServiceNow│ │ Zendesk │ │Azure DO │ │ GitHub │ │ GitLab │ │
│ └────┬────┘ └────┬────┘ └─────┬─────┘ └────┬────┘ └─────┬─────┘ └────┬────┘ │
│ │ │ │ │ │ │ │
│ └───────────┴────────────┴─────┬──────┴────────────┴────────────┘ │
│ │ │
│ HTTPS Webhooks │
│ │ │
└──────────────────────────────────────┼──────────────────────────────────────────┘
│
┌──────────────────────────────────────┼──────────────────────────────────────────┐
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────────┐ │
│ │ JIRA AI Fixer API │ │
│ │ (FastAPI + Python 3.11) │ │
│ ├─────────────────────────────────────────────────────────────────────────┤ │
│ │ │ │
│ │ ┌──────────────────────────────────────────────────────────────────┐ │ │
│ │ │ Webhook Layer │ │ │
│ │ │ /api/webhook/jira /api/webhook/servicenow /api/webhook/... │ │ │
│ │ └───────────────────────────────┬──────────────────────────────────┘ │ │
│ │ │ │ │
│ │ ┌───────────────────────────────▼──────────────────────────────────┐ │ │
│ │ │ Adapter Layer │ │ │
│ │ │ normalize_jira() normalize_servicenow() normalize_zendesk() │ │ │
│ │ └───────────────────────────────┬──────────────────────────────────┘ │ │
│ │ │ │ │
│ │ NormalizedIssue │ │
│ │ │ │ │
│ │ ┌───────────────────────────────▼──────────────────────────────────┐ │ │
│ │ │ Core Analysis Engine │ │ │
│ │ │ save_and_queue_issue() → analyze_issue() (background) │ │ │
│ │ └───────────────────────────────┬──────────────────────────────────┘ │ │
│ │ │ │ │
│ │ ┌───────────────────────┼───────────────────────┐ │ │
│ │ │ │ │ │ │
│ │ ▼ ▼ ▼ │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │ Code Fetcher │ │ LLM Client │ │ PR Creator │ │ │
│ │ │ (Gitea) │ │ (OpenRouter) │ │ (Gitea) │ │ │
│ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │
│ │ │ │
│ │ ┌──────────────────────────────────────────────────────────────────┐ │ │
│ │ │ Callback Layer │ │ │
│ │ │ post_analysis_to_source() - posts back to original system │ │ │
│ │ └──────────────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ PostgreSQL │ │ Gitea │ │ OpenRouter │ │
│ │ Database │ │ (Code Host) │ │ (LLM API) │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │
│ JIRA AI Fixer Stack │
└─────────────────────────────────────────────────────────────────────────────────┘
Component Details
1. Webhook Layer
Receives HTTP POST requests from external systems. Each endpoint is tailored to the specific payload format of the source system.
Responsibilities:
- Receive webhooks
- Basic validation
- Route to appropriate adapter
2. Adapter Layer (Normalizer)
Transforms vendor-specific payloads into a normalized internal format.
NormalizedIssue Schema:
class NormalizedIssue(BaseModel):
external_id: str # Original ID in source system
external_key: str # Human-readable key (e.g., "JIRA-123")
source: str # Source system identifier
source_url: str # Link back to original issue
title: str # Issue title/summary
description: str # Full description
priority: str # Priority level
labels: List[str] # Tags/labels
callback_url: str # URL to post results back
metadata: Dict # System-specific extra data
3. Core Analysis Engine
The heart of the system. Runs as a background task.
Pipeline:
fetch_cobol_files()- Get source code from repositoriesbuild_analysis_prompt()- Construct LLM promptcall_llm()- Send to OpenRouter APIparse_analysis()- Extract structured data from responsecreate_fix_branch_and_pr()- Generate fix PRpost_analysis_to_source()- Report results
4. Database Layer
PostgreSQL stores all issues and their analysis results.
Tables:
issues (
id SERIAL PRIMARY KEY,
external_id TEXT,
external_key TEXT,
source TEXT,
source_url TEXT,
title TEXT,
description TEXT,
status TEXT, -- pending, analyzed, error
analysis TEXT,
confidence FLOAT,
affected_files TEXT, -- JSON array
suggested_fix TEXT,
pr_url TEXT,
pr_branch TEXT,
callback_url TEXT,
metadata JSONB,
created_at TIMESTAMP,
analyzed_at TIMESTAMP
)
integrations (
id SERIAL PRIMARY KEY,
name TEXT UNIQUE,
type TEXT,
config JSONB,
enabled BOOLEAN,
last_event_at TIMESTAMP,
event_count INT
)
5. Git Integration Layer
Interfaces with Gitea for:
- Fetching source code
- Creating branches
- Committing fixes
- Opening pull requests
6. Callback Layer
Posts analysis results back to the source system. Handles different API formats:
| System | Format |
|---|---|
| JIRA | REST API v2 |
| ServiceNow | Table API |
| Zendesk | Tickets API |
| Azure DevOps | Work Items API |
| GitHub | Issues API |
| GitLab | Notes API |
Data Flow
1. Webhook Received
└─► POST /api/webhook/{source}
└─► normalize_{source}(payload)
└─► NormalizedIssue
└─► save_to_database()
└─► queue_background_task()
2. Background Analysis
└─► analyze_issue()
├─► fetch_cobol_files() ←── Gitea API
├─► build_analysis_prompt()
├─► call_llm() ←── OpenRouter API
├─► parse_analysis()
├─► create_fix_branch_and_pr() ──► Gitea API
├─► update_database()
└─► post_analysis_to_source() ──► Source System API
3. User Views Dashboard
└─► GET /api/issues
└─► query_database()
└─► return JSON
Deployment Architecture
┌─────────────────────────────────────────────────────────────┐
│ Docker Swarm Cluster │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Traefik Proxy │◄────────►│ Let's Encrypt │ │
│ │ (Edge Router) │ │ (TLS Certs) │ │
│ └────────┬────────┘ └─────────────────┘ │
│ │ │
│ │ jira-fixer.startdata.com.br │
│ │ │
│ ┌────────▼────────┐ ┌─────────────────┐ │
│ │ JIRA AI Fixer │ │ PostgreSQL │ │
│ │ API (8000) │◄────────►│ (internal) │ │
│ │ Python 3.11 │ │ │ │
│ └─────────────────┘ └─────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
External Services:
- Gitea (gitea.startdata.com.br) - Code repository
- OpenRouter (openrouter.ai) - LLM API
Security Considerations
Network Security
- All external traffic through HTTPS (TLS 1.3)
- Internal services on isolated Docker network
- Database not exposed externally
Authentication
- Webhook secrets (optional) for validation
- Gitea token for repository access
- OpenRouter API key for LLM
Data Privacy
- Issue descriptions may contain sensitive data
- LLM calls go to external service (OpenRouter)
- Consider self-hosted LLM for sensitive environments
Scalability
Current Limits
- Single API instance
- ~50 concurrent analyses
- ~1000 issues/day throughput
Scaling Options
- Horizontal: Add more API replicas
- Queue: Add Redis for job queue
- Database: PostgreSQL read replicas
- LLM: Multiple OpenRouter API keys
Monitoring
Health Check
GET /api/health
→ {"status": "healthy", "service": "jira-ai-fixer", "version": "2.0.0"}
Metrics Endpoint
GET /api/stats
→ {
"total": 150,
"analyzed": 142,
"prs_created": 98,
"avg_confidence": 85,
"by_source": {"jira": 80, "servicenow": 50, "tickethub": 20}
}
Future Enhancements
- Multi-language Support: Java, Python, JavaScript analysis
- Custom LLM Models: Support for local/private models
- Repository Indexing: Full codebase embeddings for better context
- Automated Testing: Run tests on fix branches
- Approval Workflow: Require human approval before PR
Document Version: 2.0 Last Updated: February 2026 StartData Engineering