# malikjahanzaib/issue2pr architecture

> Architecture diagram of the GitHub repository malikjahanzaib/issue2pr, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/malikjahanzaib/issue2pr
- Repository: https://github.com/malikjahanzaib/issue2pr

## Overview

##### Project Type and Purpose
- This is an open-source, backend-only GitHub bot (Issue2PR) whose job is to listen for GitHub issue events, run AI-powered code generation, and automatically open pull requests. It also provides CLI utilities for repository maintenance (closing issues/PRs, deleting branches).

##### File Structure Analysis
- Top-level scripts:
- main.py            – HTTP server entry point (webhook listener)
- ai_engine.py       – Encapsulates AI calls (OpenAI API)
- issue_parser.py    – Parses incoming issue payloads
- github_handler.py  – Wraps GitHub REST API interactions
- config.py          – Loads env vars and exposes configuration
- close_issues.py    – CLI utility to batch-close issues/PRs
- delete_branches.py – CLI utility to remove stale branches
- test_issue_processing.py – Test harness (test mode, no real PRs)
- scripts/issue_analysis.py – Auxiliary analysis script
- .github/workflows/pylint.yml – CI linting
- requirements.txt, .env.example, .gitignore

##### README Insights
- The service uses Python 3.8+, Flask (or similar) for webhooks, ngrok for local tunneling, OpenAI and GitHub APIs, optional Slack/Discord notifications, robust logging, and a “test mode.”
- No persistent database is mentioned—state is ephemeral or managed via GitHub branches.

1. Webhook Listener (main.py + HTTP framework)
2. Issue Parser (issue_parser.py)
3. AI Engine (ai_engine.py → OpenAI API)
4. GitHub Handler (github_handler.py → GitHub API)
5. Notification Service (optional Slack/Discord clients)
6. Configuration & Logging (config.py + log files)
7. CLI Utilities (close_issues.py, delete_branches.py, test_issue_processing.py)

- GitHub Webhook → Webhook Listener
- Listener → Issue Parser
- Parser → AI Engine → OpenAI
- AI Engine (diff output) → GitHub Handler → GitHub (branches, commits, PRs)
- GitHub Handler → Notification Service → Slack/Discord (if configured)
- All components → Logging subsystem
- CLI Utilities → GitHub Handler (reuse API layer)

c. Architectural Patterns & Principles
- Layered modular design: Each module has a single responsibility
- External integration points are encapsulated (OpenAI API, GitHub API, Slack/Discord)
- “Test mode” isolates side effects (no real PR creation)
- Utilities reuse core handler code, avoiding duplication

d. Key Technologies & Frameworks
- Python 3.8+
- HTTP framework (e.g., Flask or FastAPI) for the listener
- requests or httpx for API calls
- OpenAI SDK
- GitHub REST API
- ngrok (development)
- Logging library (built-in logging)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Trigger
    ext_GitHubWebhook["GitHub Webhook"]:::external

    %% Core Service Components
    main["Webhook Listener\n(main.py)"]:::internal
    issue["Issue Parser\n(issue_parser.py)"]:::internal
    ai["AI Engine\n(ai_engine.py)"]:::internal
    gh["GitHub Handler\n(github_handler.py)"]:::internal
    notif["Notification Service"]:::external
    config["Configuration & Logging\n(config.py\n.env)"]:::utility
    logs["Log Storage"]:::storage

    %% External Services
    openai["OpenAI API"]:::external
    githubapi["GitHub API"]:::external
    slack["Slack"]:::external
    discord["Discord"]:::external

    %% Utilities
    subgraph "CLI Utilities"
        close["Close Issues/PRs\n(close_issues.py)"]:::utility
        delb["Delete Stale Branches\n(delete_branches.py)"]:::utility
        test["Test Mode Harness\n(test_issue_processing.py)"]:::utility
    end

    %% Auxiliary Scripts and CI
    aux["Auxiliary Analysis Script\n(scripts/issue_analysis.py)"]:::internal
    ci["CI Linting Pipeline\n(.github/workflows/pylint.yml)"]:::utility

    %% Data Flow
    ext_GitHubWebhook --> main
    main --> issue
    issue --> ai
    ai --> openai
    ai --> gh
    gh --> githubapi
    gh --> notif
    notif --> slack
    notif --> discord

    %% Config and Logging Connections
    config --> main
    config --> issue
    config --> ai
    config --> gh
    config --> notif
    main --> logs
    issue --> logs
    ai --> logs
    gh --> logs
    notif --> logs

    %% Utilities Reusing Handler
    close --> gh
    delb --> gh
    test --> gh
    close --> logs
    delb --> logs
    test --> logs

    %% Auxiliary and CI
    aux --> logs
    ci --> main
    ci --> issue
    ci --> ai
    ci --> gh
    ci --> close
    ci --> delb

    %% Click Events
    click main "https://github.com/malikjahanzaib/issue2pr/blob/main/main.py"
    click issue "https://github.com/malikjahanzaib/issue2pr/blob/main/issue_parser.py"
    click ai "https://github.com/malikjahanzaib/issue2pr/blob/main/ai_engine.py"
    click gh "https://github.com/malikjahanzaib/issue2pr/blob/main/github_handler.py"
    click config "https://github.com/malikjahanzaib/issue2pr/blob/main/config.py"
    click close "https://github.com/malikjahanzaib/issue2pr/blob/main/close_issues.py"
    click delb "https://github.com/malikjahanzaib/issue2pr/blob/main/delete_branches.py"
    click test "https://github.com/malikjahanzaib/issue2pr/blob/main/test_issue_processing.py"
    click aux "https://github.com/malikjahanzaib/issue2pr/blob/main/scripts/issue_analysis.py"
    click ci "https://github.com/malikjahanzaib/issue2pr/blob/main/.github/workflows/pylint.yml"

    %% Styles
    classDef internal fill:#cce5ff,stroke:#004085,color:#004085
    classDef external fill:#d4edda,stroke:#155724,color:#155724
    classDef utility fill:#e2e3e5,stroke:#6c757d,color:#6c757d
    classDef storage fill:#f8d7da,stroke:#721c24,color:#721c24
```
