289 lines
16 KiB
Markdown
289 lines
16 KiB
Markdown
# 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:**
|
|
```python
|
|
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:**
|
|
1. `fetch_cobol_files()` - Get source code from repositories
|
|
2. `build_analysis_prompt()` - Construct LLM prompt
|
|
3. `call_llm()` - Send to OpenRouter API
|
|
4. `parse_analysis()` - Extract structured data from response
|
|
5. `create_fix_branch_and_pr()` - Generate fix PR
|
|
6. `post_analysis_to_source()` - Report results
|
|
|
|
### 4. Database Layer
|
|
|
|
PostgreSQL stores all issues and their analysis results.
|
|
|
|
**Tables:**
|
|
```sql
|
|
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
|
|
1. **Horizontal**: Add more API replicas
|
|
2. **Queue**: Add Redis for job queue
|
|
3. **Database**: PostgreSQL read replicas
|
|
4. **LLM**: Multiple OpenRouter API keys
|
|
|
|
## Monitoring
|
|
|
|
### Health Check
|
|
```bash
|
|
GET /api/health
|
|
→ {"status": "healthy", "service": "jira-ai-fixer", "version": "2.0.0"}
|
|
```
|
|
|
|
### Metrics Endpoint
|
|
```bash
|
|
GET /api/stats
|
|
→ {
|
|
"total": 150,
|
|
"analyzed": 142,
|
|
"prs_created": 98,
|
|
"avg_confidence": 85,
|
|
"by_source": {"jira": 80, "servicenow": 50, "tickethub": 20}
|
|
}
|
|
```
|
|
|
|
## Future Enhancements
|
|
|
|
1. **Multi-language Support**: Java, Python, JavaScript analysis
|
|
2. **Custom LLM Models**: Support for local/private models
|
|
3. **Repository Indexing**: Full codebase embeddings for better context
|
|
4. **Automated Testing**: Run tests on fix branches
|
|
5. **Approval Workflow**: Require human approval before PR
|
|
|
|
---
|
|
|
|
*Document Version: 2.0*
|
|
*Last Updated: February 2026*
|
|
*StartData Engineering*
|