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