# deepak-menan-r/jiraresolver architecture

> Architecture diagram of the GitHub repository deepak-menan-r/jiraresolver, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/deepak-menan-r/jiraresolver
- Repository: https://github.com/deepak-menan-r/jiraresolver

## Overview

#### Purpose and Runtime Entry Points
This is a Python 3.10+ agentic Jira resolver: given a Jira ticket ID, it discovers the relevant GitHub repository, proposes a fix, obtains human approval, then creates a PR and updates Jira. It runs as two local processes:
- Agent CLI: `src/jira_resolver_mcp/__main__.py`, `src/jira_resolver_mcp/main.py`
- MCP HTTP server: `mcp_server/__main__.py`, `mcp_server/run.py`

#### Agent Orchestration
LangGraph is the control-plane runtime. `build_workflow()` wires a stateful graph beginning with ticket intake and ending in either rejection, clarification, retry exhaustion, or GitHub operations.
- Graph and conditional routing: `src/jira_resolver_mcp/workflow.py`
- Per-stage logic: `src/jira_resolver_mcp/nodes.py`
- Cross-node state/checkpoint payload: `src/jira_resolver_mcp/state.py`

The graph pauses through a human-approval interrupt before any write to GitHub.

#### Ticket Intake and Repository Navigation
The ticket stage fetches Jira data, validates required details, extracts repository/file hints, marks the ticket Working, and terminates early for missing information. Navigation resolves a repo without a supplied URL: it lists accessible repositories, searches code across them, identifies the likely match, reads architecture files, searches within the target repository, ranks candidates, and loads source content.
- Agent stages: `src/jira_resolver_mcp/nodes.py`
- LLM-assisted extraction/selection: `src/jira_resolver_mcp/llm_router.py`
- Jira/repository server tools: `mcp_server/tools_jira.py`, `mcp_server/tools_repo.py`

Ambiguous repository selection is a boundary: the system posts a Jira clarification and waits rather than modifying code.

#### Planning, Implementation, and Review Loop
Once candidate file contents are in graph state, the planner produces an implementation plan. The implementer generates complete updated file contents, while the reviewer independently assesses the proposal. Rejected reviews increment retries and route back to implementation; acceptance requires reviewer confidence of at least 0.75 and transitions Jira to In Review.
- LLM interface and placeholder provider bodies: `src/jira_resolver_mcp/llm_router.py`
- Workflow stages/retry behavior: `src/jira_resolver_mcp/nodes.py`, `src/jira_resolver_mcp/workflow.py`

LLM integration is intentionally incomplete; configured OpenRouter and Google API credentials are expected future provider options.

#### Approval and GitHub Write Boundary
Human approval separates read/analysis operations from repository mutation. On approval, GitHub operations create a timestamped `jira/<ticket>-...` branch, apply generated file changes or patch, create a PR, checkpoint state for resume paths, post the PR URL to Jira, and mark the ticket PR Created.
- Approval and finalization stages: `src/jira_resolver_mcp/nodes.py`
- GitHub mutation handlers: `mcp_server/tools_github.py`
- Resume-oriented CLI flow: `src/jira_resolver_mcp/main.py`

#### MCP Service Boundary
The agent never calls Jira or GitHub directly. Its typed client wraps the MCP server’s single tool-dispatch API (`POST /tools/call`), while FastAPI registers and dispatches Jira, repository-discovery, and GitHub tools. Health and tool-list endpoints support local operation.
- Agent-side HTTP abstraction: `src/jira_resolver_mcp/mcp_client.py`
- FastAPI app/tool registry: `mcp_server/app.py`
- MCP server configuration: `mcp_server/config.py`

#### Infrastructure and External Services
The MCP server runs under Uvicorn/FastAPI, normally at `http://localhost:8080`. It requires Jira Cloud REST credentials and a GitHub PAT with repository access; repository discovery can be scoped to a GitHub organization or user. Environment-driven configuration covers service URLs, credentials, default branch, host/port, and optional LLM provider keys.
- Server process: `mcp_server/run.py`
- Agent configuration: `src/jira_resolver_mcp/config.py`
- Environment contract: `.env.example`

Main entry points: [`src/jira_resolver_mcp/nodes.py`](https://github.com/deepak-menan-r/jiraresolver/blob/main/src/jira_resolver_mcp/nodes.py) (Workflow stages), [`mcp_server/app.py`](https://github.com/deepak-menan-r/jiraresolver/blob/main/mcp_server/app.py) (Tool dispatch API), [`src/jira_resolver_mcp/workflow.py`](https://github.com/deepak-menan-r/jiraresolver/blob/main/src/jira_resolver_mcp/workflow.py) (LangGraph workflow), [`src/jira_resolver_mcp/main.py`](https://github.com/deepak-menan-r/jiraresolver/blob/main/src/jira_resolver_mcp/main.py) (Resume flow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agent["Agent process"]
  node_agent_cli["Agent CLI<br/>Python entry point<br/>[__main__.py]"]
  node_agent_main["Resume flow<br/>CLI runtime<br/>[main.py]"]
  node_workflow{{"LangGraph workflow<br/>control plane<br/>[workflow.py]"}}
  node_nodes["Workflow stages<br/>agent stages<br/>[nodes.py]"]
  node_state["Workflow state<br/>checkpoint payload<br/>[state.py]"]
  node_llm["LLM router<br/>LLM interface<br/>[llm_router.py]"]
  node_mcp_client["Typed MCP client<br/>HTTP client<br/>[mcp_client.py]"]
  node_agent_config["Agent configuration<br/>environment config<br/>[config.py]"]
end

subgraph group_mcp["MCP server"]
  node_server_entry["MCP server process<br/>Python entry point<br/>[__main__.py]"]
  node_server_run["Uvicorn runner<br/>server runtime<br/>[run.py]"]
  node_mcp_app{{"Tool dispatch API<br/>FastAPI app<br/>[app.py]"}}
  node_server_config["Server configuration<br/>environment config<br/>[config.py]"]
  node_jira_tools["Jira tools<br/>MCP tools<br/>[tools_jira.py]"]
  node_repo_tools["Repository discovery<br/>MCP tools<br/>[tools_repo.py]"]
  node_github_tools["GitHub mutation<br/>MCP tools<br/>[tools_github.py]"]
end

subgraph group_external["External services"]
  node_jira[("Jira Cloud<br/>external API")]
  node_github[("GitHub<br/>external API")]
  node_human(("Human approver<br/>approval boundary"))
  node_llm_providers["LLM providers<br/>future provider APIs"]
end

node_agent_cli -->|"starts"| node_agent_main
node_agent_main -->|"runs or resumes"| node_workflow
node_workflow -->|"executes stages"| node_nodes
node_workflow -->|"reads and checkpoints"| node_state
node_nodes -->|"delegates extraction, planning, implementation, review"| node_llm
node_nodes -->|"requests tools"| node_mcp_client
node_nodes -.->|"approval interrupt"| node_human
node_human -.->|"approval or rejection"| node_nodes
node_agent_config -.->|"configures"| node_agent_main
node_llm -.->|"provider calls"| node_llm_providers
node_mcp_client -->|"POST /tools/call"| node_mcp_app
node_server_entry -->|"starts"| node_server_run
node_server_run -->|"serves"| node_mcp_app
node_server_config -.->|"configures"| node_mcp_app
node_mcp_app -->|"dispatches"| node_jira_tools
node_mcp_app -->|"dispatches"| node_repo_tools
node_mcp_app -->|"dispatches"| node_github_tools
node_jira_tools -->|"ticket reads and updates"| node_jira
node_repo_tools -->|"repository search and reads"| node_github
node_github_tools -->|"branch, changes, PR"| node_github
node_nodes -.->|"review rejection retries implementation"| node_nodes

click node_agent_cli "https://github.com/deepak-menan-r/jiraresolver/blob/main/src/jira_resolver_mcp/__main__.py"
click node_agent_main "https://github.com/deepak-menan-r/jiraresolver/blob/main/src/jira_resolver_mcp/main.py"
click node_workflow "https://github.com/deepak-menan-r/jiraresolver/blob/main/src/jira_resolver_mcp/workflow.py"
click node_nodes "https://github.com/deepak-menan-r/jiraresolver/blob/main/src/jira_resolver_mcp/nodes.py"
click node_state "https://github.com/deepak-menan-r/jiraresolver/blob/main/src/jira_resolver_mcp/state.py"
click node_llm "https://github.com/deepak-menan-r/jiraresolver/blob/main/src/jira_resolver_mcp/llm_router.py"
click node_mcp_client "https://github.com/deepak-menan-r/jiraresolver/blob/main/src/jira_resolver_mcp/mcp_client.py"
click node_agent_config "https://github.com/deepak-menan-r/jiraresolver/blob/main/src/jira_resolver_mcp/config.py"
click node_server_entry "https://github.com/deepak-menan-r/jiraresolver/blob/main/mcp_server/__main__.py"
click node_server_run "https://github.com/deepak-menan-r/jiraresolver/blob/main/mcp_server/run.py"
click node_mcp_app "https://github.com/deepak-menan-r/jiraresolver/blob/main/mcp_server/app.py"
click node_server_config "https://github.com/deepak-menan-r/jiraresolver/blob/main/mcp_server/config.py"
click node_jira_tools "https://github.com/deepak-menan-r/jiraresolver/blob/main/mcp_server/tools_jira.py"
click node_repo_tools "https://github.com/deepak-menan-r/jiraresolver/blob/main/mcp_server/tools_repo.py"
click node_github_tools "https://github.com/deepak-menan-r/jiraresolver/blob/main/mcp_server/tools_github.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_agent_cli,node_agent_main,node_workflow,node_nodes,node_state,node_llm,node_mcp_client,node_agent_config toneBlue
class node_server_entry,node_server_run,node_mcp_app,node_server_config,node_jira_tools,node_repo_tools,node_github_tools toneAmber
class node_jira,node_github,node_human,node_llm_providers toneMint
```

## Components

### Agent process

Local LangGraph CLI runtime.

- [Agent CLI](https://github.com/deepak-menan-r/jiraresolver/blob/main/src/jira_resolver_mcp/__main__.py): Python entry point · `src/jira_resolver_mcp/__main__.py`
- [Resume flow](https://github.com/deepak-menan-r/jiraresolver/blob/main/src/jira_resolver_mcp/main.py): CLI runtime · Starts and resumes workflow runs. · `src/jira_resolver_mcp/main.py`
- [LangGraph workflow](https://github.com/deepak-menan-r/jiraresolver/blob/main/src/jira_resolver_mcp/workflow.py): control plane · Routes ticket resolution, review retries, and terminal outcomes. · `src/jira_resolver_mcp/workflow.py`
- [Workflow stages](https://github.com/deepak-menan-r/jiraresolver/blob/main/src/jira_resolver_mcp/nodes.py): agent stages · Ticket, navigation, planning, review, approval, and finalization logic. · `src/jira_resolver_mcp/nodes.py`
- [Workflow state](https://github.com/deepak-menan-r/jiraresolver/blob/main/src/jira_resolver_mcp/state.py): checkpoint payload · Cross-stage state retained for approval and resume. · `src/jira_resolver_mcp/state.py`
- [LLM router](https://github.com/deepak-menan-r/jiraresolver/blob/main/src/jira_resolver_mcp/llm_router.py): LLM interface · Extracts hints, selects repositories, plans, implements, and reviews. · `src/jira_resolver_mcp/llm_router.py`
- [Typed MCP client](https://github.com/deepak-menan-r/jiraresolver/blob/main/src/jira_resolver_mcp/mcp_client.py): HTTP client · Agent's sole Jira and GitHub access path. · `src/jira_resolver_mcp/mcp_client.py`
- [Agent configuration](https://github.com/deepak-menan-r/jiraresolver/blob/main/src/jira_resolver_mcp/config.py): environment config · `src/jira_resolver_mcp/config.py`

### MCP server

Local HTTP tool boundary.

- [MCP server process](https://github.com/deepak-menan-r/jiraresolver/blob/main/mcp_server/__main__.py): Python entry point · `mcp_server/__main__.py`
- [Uvicorn runner](https://github.com/deepak-menan-r/jiraresolver/blob/main/mcp_server/run.py): server runtime · Runs FastAPI locally, normally on port 8080. · `mcp_server/run.py`
- [Tool dispatch API](https://github.com/deepak-menan-r/jiraresolver/blob/main/mcp_server/app.py): FastAPI app · Exposes POST /tools/call plus health and tool-list endpoints. · `mcp_server/app.py`
- [Server configuration](https://github.com/deepak-menan-r/jiraresolver/blob/main/mcp_server/config.py): environment config · `mcp_server/config.py`
- [Jira tools](https://github.com/deepak-menan-r/jiraresolver/blob/main/mcp_server/tools_jira.py): MCP tools · Fetches, updates, and clarifies tickets. · `mcp_server/tools_jira.py`
- [Repository discovery](https://github.com/deepak-menan-r/jiraresolver/blob/main/mcp_server/tools_repo.py): MCP tools · Lists repositories and searches architecture, code, and source files. · `mcp_server/tools_repo.py`
- [GitHub mutation](https://github.com/deepak-menan-r/jiraresolver/blob/main/mcp_server/tools_github.py): MCP tools · Creates branch, applies changes, and opens pull requests. · `mcp_server/tools_github.py`

### External services

- **Jira Cloud**: external API
- **GitHub**: external API
- **Human approver**: approval boundary · Must approve before repository writes.
- **LLM providers**: future provider APIs · OpenRouter and Google credentials are supported as future options.

## Connections

- Agent CLI → Resume flow: starts
- Resume flow → LangGraph workflow: runs or resumes
- LangGraph workflow → Workflow stages: executes stages
- LangGraph workflow → Workflow state: reads and checkpoints
- Workflow stages → LLM router: delegates extraction, planning, implementation, review
- Workflow stages → Typed MCP client: requests tools
- Workflow stages → Human approver: approval interrupt
- Human approver → Workflow stages: approval or rejection
- Agent configuration → Resume flow: configures
- LLM router → LLM providers: provider calls
- Typed MCP client → Tool dispatch API: POST /tools/call
- MCP server process → Uvicorn runner: starts
- Uvicorn runner → Tool dispatch API: serves
- Server configuration → Tool dispatch API: configures
- Tool dispatch API → Jira tools: dispatches
- Tool dispatch API → Repository discovery: dispatches
- Tool dispatch API → GitHub mutation: dispatches
- Jira tools → Jira Cloud: ticket reads and updates
- Repository discovery → GitHub: repository search and reads
- GitHub mutation → GitHub: branch, changes, PR
- Workflow stages → Workflow stages: review rejection retries implementation