# mulhamna/jira-commands architecture

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

- Interactive diagram: https://gitdiagram.com/mulhamna/jira-commands
- Repository: https://github.com/mulhamna/jira-commands

## Overview

1. **Repository shape: a Rust workspace around one shared Jira engine**
   - This repo is organized as a Cargo workspace with a shared library and multiple frontends.
   - The central boundary is: **Jira protocol/domain logic lives in `jira-core`**, while `jira`, `jira-mcp`, and `zed-jira` are consumers/wrappers around it.

2. **Core subsystem: `crates/jira-core` is the integration layer with Jira**
   - `jira-core` owns the low-level Jira client, auth handling, config loading, API error types, field caching, ADF conversion, and typed models.
   - Its model layer covers the main Jira objects the product manipulates: issues, comments, attachments, links, worklogs, transitions, versions, components, users, sprints, and fields.
   - This crate is the main boundary between the repo and external Jira Cloud / Jira Data Center REST APIs.

3. **Authentication and profile/config flow**
   - The app is profile-based: config is loaded from a user config file, with environment variables able to override the active profile.
   - Multiple deployments are supported through stored profiles, each carrying base URL, credentials, deployment type, API version, timeout, and project defaults.
   - The auth/config path feeds the shared client, so every frontend inherits the same login model and server selection behavior.

4. **Primary user-facing binary: `crates/jira`**
   - `jira` is the main CLI application and the most feature-rich frontend.
   - It exposes subcommand groups for auth, issue management, raw API calls, plans, MCP install/doctor flows, and the TUI launcher.
   - The CLI is the orchestration layer: it parses user intent, calls `jira-core`, and formats results back to the terminal.

5. **Issue-management command pipeline**
   - Most operational flows go through `jira issue ...`: list/view/create/update/transition/move/clone/delete, attachments, worklogs, links, bulk operations, version management, and JQL builder flows.
   - There is a clear request path: command arguments or interactive prompts → CLI logic → shared Jira client → Jira REST API → formatted terminal output.
   - Bulk commands accept JQL, explicit keys, or manifests, so the CLI can drive both ad hoc and batch operations.

6. **Interactive TUI subsystem inside `crates/jira`**
   - The TUI is a full-screen stateful frontend for browsing, editing, and bulk-managing issues without leaving the terminal.
   - Its internal modules separate UI concerns: app state, columns, modes, mouse/key handling, modal dialogs, render/theme, picker/prompts, and preference persistence.
   - The TUI depends on the same shared client and models, but adds richer interaction state, split master-detail rendering, and mouse-driven navigation.

7. **Markdown-to-Jira content transformation**
   - The repo includes an ADF layer and a “render” path for converting Markdown-like input into Jira’s Atlassian Document Format JSON and/or plain text previews.
   - This is important because issue descriptions/comments can be authored in more natural text but must be sent to Jira in ADF-compatible form.
   - In architecture terms, this is a content transformation boundary between local text input and Jira’s structured document model.

8. **Optional MCP server: `crates/jira-mcp`**
   - `jira-mcp` exposes Jira capabilities as typed Model Context Protocol tools for editors and AI agents.
   - It sits on top of the same shared core client, so it is not a separate integration stack; it is another frontend to the same Jira domain layer.
   - The server’s role is adapter-style: map MCP requests into Jira operations and normalize errors for tool consumers.

9. **Editor integration and extension mirroring**
   - `crates/zed-jira` is a Zed extension packaging target, with schema/default settings and extension metadata.
   - The repo also contains a `plugin/` tree with Claude plugin metadata and skills, indicating the project is distributed into multiple agent/editor ecosystems.
   - These integration surfaces are distinct from the CLI/MCP server, but they reuse the same Jira semantics and installation/update conventions.

10. **Distribution and packaging layer**
   - Release artifacts are produced for several channels: Cargo, npm wrapper, Scoop, Winget, Chocolatey, and install scripts.
   - The `packaging/` directory and helper scripts automate generation/updates of those distribution manifests.
   - This means the repo’s architecture includes a build-and-release boundary, not just runtime code.

11. **Operational metadata and runtime discovery**
   - The app discovers custom fields at runtime and caches them, rather than hardcoding field IDs or schemas.
   - That makes Jira instance differences part of the runtime model, not the build-time model.
   - Related support code includes version checking/insights and notification handling inside the CLI app.

12. **Quality, security, and release automation**
   - GitHub Actions, release-please, security workflows, and package submission scripts form the delivery pipeline.
   - There is also fuzzing support for Markdown/ADF handling and a clusterfuzzlite container, which is relevant because input parsing/conversion is a likely edge-case boundary.
   - These pieces do not affect day-to-day runtime architecture, but they matter for understanding how the repo is validated and shipped.

13. **End-to-end data flow summary**
   - User input enters through one of three front doors: CLI, TUI, or MCP server.
   - Those frontends converge on `jira-core` for auth, request construction, model decoding, and Jira REST communication.
   - Jira responses come back as typed domain objects, are optionally cached/transformed, and are rendered either as terminal output, interactive UI state, or tool responses for external clients.

Main entry points: [`crates/jira-core/src/lib.rs`](https://github.com/mulhamna/jira-commands/blob/main/crates/jira-core/src/lib.rs) (jira-core), [`crates/jira/src/cli/mod.rs`](https://github.com/mulhamna/jira-commands/blob/main/crates/jira/src/cli/mod.rs) (Commands), [`Cargo.toml`](https://github.com/mulhamna/jira-commands/blob/main/Cargo.toml) (Cargo workspace), [`crates/jira/src/main.rs`](https://github.com/mulhamna/jira-commands/blob/main/crates/jira/src/main.rs) (jira)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Workspace"]
  node_workspace_root["Cargo workspace<br/>[Cargo.toml]"]
end

subgraph group_core["Jira Core"]
  node_jira_core["jira-core<br/>[lib.rs]"]
  node_jira_core_client["Client<br/>[client.rs]"]
  node_jira_core_auth["Auth<br/>[auth.rs]"]
  node_jira_core_config["Config<br/>[config.rs]"]
  node_jira_core_adf["ADF<br/>content transform<br/>[adf.rs]"]
  node_jira_core_cache["Field cache<br/>runtime cache<br/>[field_cache.rs]"]
  node_jira_models["Models<br/>[mod.rs]"]
end

subgraph group_cli["CLI App"]
  node_jira_bin["jira<br/>cli binary<br/>[main.rs]"]
  node_jira_cli["Commands<br/>cli router<br/>[mod.rs]"]
  node_jira_issue["Issue flow<br/>issue commands<br/>[issue.rs]"]
  node_jira_api["API calls<br/>raw api<br/>[api.rs]"]
  node_jira_auth["Auth cmd<br/>cli auth<br/>[auth.rs]"]
  node_jira_tui["TUI<br/>terminal ui<br/>[mod.rs]"]
end

subgraph group_integrations["Integrations"]
  node_jira_mcp["jira-mcp<br/>mcp server<br/>[main.rs]"]
  node_zed_jira["zed-jira<br/>editor extension<br/>[lib.rs]"]
  node_claude_plugin["Claude plugin<br/>agent plugin<br/>[plugin.json]"]
end

subgraph group_distribution["Packaging"]
  node_packaging["Packaging<br/>distribution<br/>[package.json]"]
end

subgraph group_automation["Automation"]
  node_github_actions["CI/CD<br/>automation<br/>[ci.yml]"]
  node_fuzzing["Fuzzing<br/>input hardening<br/>[markdown_adf.rs]"]
end

node_workspace_root -->|"includes"| node_jira_core
node_workspace_root -->|"includes"| node_jira_bin
node_workspace_root -->|"includes"| node_jira_mcp
node_workspace_root -->|"includes"| node_zed_jira
node_jira_bin -->|"routes"| node_jira_cli
node_jira_cli -->|"delegates"| node_jira_auth
node_jira_cli -->|"delegates"| node_jira_issue
node_jira_cli -->|"delegates"| node_jira_api
node_jira_cli -->|"launches"| node_jira_tui
node_jira_issue -->|"uses"| node_jira_core
node_jira_api -->|"uses"| node_jira_core_client
node_jira_auth -->|"uses"| node_jira_core_auth
node_jira_tui -->|"uses"| node_jira_core
node_jira_tui -->|"caches"| node_jira_core_cache
node_jira_core -->|"contains"| node_jira_core_client
node_jira_core -->|"contains"| node_jira_core_auth
node_jira_core -->|"contains"| node_jira_core_config
node_jira_core -->|"contains"| node_jira_core_adf
node_jira_core -->|"contains"| node_jira_core_cache
node_jira_core -->|"contains"| node_jira_models
node_jira_mcp -->|"adapts"| node_jira_core
node_zed_jira -->|"depends on"| node_jira_core
node_claude_plugin -->|"reflects"| node_jira_core
node_packaging -->|"packages"| node_jira_bin
node_packaging -->|"packages"| node_zed_jira
node_github_actions -->|"builds"| node_packaging
node_github_actions -->|"validates"| node_jira_bin
node_github_actions -->|"validates"| node_jira_core
node_fuzzing -->|"hardens"| node_jira_core_adf
node_fuzzing -->|"hardens"| node_jira_core

click node_workspace_root "https://github.com/mulhamna/jira-commands/blob/main/Cargo.toml"
click node_jira_core "https://github.com/mulhamna/jira-commands/blob/main/crates/jira-core/src/lib.rs"
click node_jira_core_client "https://github.com/mulhamna/jira-commands/blob/main/crates/jira-core/src/client.rs"
click node_jira_core_auth "https://github.com/mulhamna/jira-commands/blob/main/crates/jira-core/src/auth.rs"
click node_jira_core_config "https://github.com/mulhamna/jira-commands/blob/main/crates/jira-core/src/config.rs"
click node_jira_core_adf "https://github.com/mulhamna/jira-commands/blob/main/crates/jira-core/src/adf.rs"
click node_jira_core_cache "https://github.com/mulhamna/jira-commands/blob/main/crates/jira-core/src/field_cache.rs"
click node_jira_models "https://github.com/mulhamna/jira-commands/blob/main/crates/jira-core/src/model/mod.rs"
click node_jira_bin "https://github.com/mulhamna/jira-commands/blob/main/crates/jira/src/main.rs"
click node_jira_cli "https://github.com/mulhamna/jira-commands/blob/main/crates/jira/src/cli/mod.rs"
click node_jira_issue "https://github.com/mulhamna/jira-commands/blob/main/crates/jira/src/cli/issue.rs"
click node_jira_api "https://github.com/mulhamna/jira-commands/blob/main/crates/jira/src/cli/api.rs"
click node_jira_auth "https://github.com/mulhamna/jira-commands/blob/main/crates/jira/src/cli/auth.rs"
click node_jira_tui "https://github.com/mulhamna/jira-commands/blob/main/crates/jira/src/tui/mod.rs"
click node_jira_mcp "https://github.com/mulhamna/jira-commands/blob/main/crates/jira-mcp/src/main.rs"
click node_zed_jira "https://github.com/mulhamna/jira-commands/blob/main/crates/zed-jira/src/lib.rs"
click node_claude_plugin "https://github.com/mulhamna/jira-commands/blob/main/plugin/.claude-plugin/plugin.json"
click node_packaging "https://github.com/mulhamna/jira-commands/blob/main/packaging/npm/package.json"
click node_github_actions "https://github.com/mulhamna/jira-commands/blob/main/.github/workflows/ci.yml"
click node_fuzzing "https://github.com/mulhamna/jira-commands/blob/main/fuzz/fuzz_targets/markdown_adf.rs"

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_workspace_root toneBlue
class node_jira_core,node_jira_core_client,node_jira_core_auth,node_jira_core_config,node_jira_core_adf,node_jira_core_cache,node_jira_models toneAmber
class node_jira_bin,node_jira_cli,node_jira_issue,node_jira_api,node_jira_auth,node_jira_tui toneMint
class node_jira_mcp,node_zed_jira,node_claude_plugin toneRose
class node_packaging toneIndigo
class node_github_actions,node_fuzzing toneTeal
```

## Components

### Workspace

Cargo workspace and shared repository boundary

- [Cargo workspace](https://github.com/mulhamna/jira-commands/blob/main/Cargo.toml): workspace · Top-level Rust workspace that ties crates together · `Cargo.toml`

### Jira Core

Shared Jira integration and domain layer

- [jira-core](https://github.com/mulhamna/jira-commands/blob/main/crates/jira-core/src/lib.rs): library · Shared Jira client, config, auth, ADF, and domain models · `crates/jira-core/src/lib.rs`
- [Client](https://github.com/mulhamna/jira-commands/blob/main/crates/jira-core/src/client.rs): api client · Low-level Jira request/response boundary · `crates/jira-core/src/client.rs`
- [Auth](https://github.com/mulhamna/jira-commands/blob/main/crates/jira-core/src/auth.rs): config auth · Profile-based credentials and server selection · `crates/jira-core/src/auth.rs`
- [Config](https://github.com/mulhamna/jira-commands/blob/main/crates/jira-core/src/config.rs): profile config · Loads active profile and deployment settings · `crates/jira-core/src/config.rs`
- [ADF](https://github.com/mulhamna/jira-commands/blob/main/crates/jira-core/src/adf.rs): content transform · Markdown and text conversion to Jira document format · `crates/jira-core/src/adf.rs`
- [Field cache](https://github.com/mulhamna/jira-commands/blob/main/crates/jira-core/src/field_cache.rs): runtime cache · Caches discovered custom fields and metadata · `crates/jira-core/src/field_cache.rs`
- [Models](https://github.com/mulhamna/jira-commands/blob/main/crates/jira-core/src/model/mod.rs): domain models · Typed Jira issues, comments, links, worklogs, versions, users, and related objects · `crates/jira-core/src/model/mod.rs`

### CLI App

Primary terminal application and TUI

- [jira](https://github.com/mulhamna/jira-commands/blob/main/crates/jira/src/main.rs): cli binary · Main command-line frontend and orchestration layer · `crates/jira/src/main.rs`
- [Commands](https://github.com/mulhamna/jira-commands/blob/main/crates/jira/src/cli/mod.rs): cli router · Subcommand routing for auth, issues, API, plans, MCP install, and TUI launch · `crates/jira/src/cli/mod.rs`
- [Issue flow](https://github.com/mulhamna/jira-commands/blob/main/crates/jira/src/cli/issue.rs): issue commands · List, view, create, update, transition, move, clone, delete, and bulk issue operations · `crates/jira/src/cli/issue.rs`
- [API calls](https://github.com/mulhamna/jira-commands/blob/main/crates/jira/src/cli/api.rs): raw api · Direct API command path for advanced requests · `crates/jira/src/cli/api.rs`
- [Auth cmd](https://github.com/mulhamna/jira-commands/blob/main/crates/jira/src/cli/auth.rs): cli auth · CLI login and profile management surface · `crates/jira/src/cli/auth.rs`
- [TUI](https://github.com/mulhamna/jira-commands/blob/main/crates/jira/src/tui/mod.rs): terminal ui · Full-screen issue browser and editor experience · `crates/jira/src/tui/mod.rs`

### Integrations

MCP, editor, and plugin surfaces

- [jira-mcp](https://github.com/mulhamna/jira-commands/blob/main/crates/jira-mcp/src/main.rs): mcp server · Model Context Protocol server exposing Jira tools · `crates/jira-mcp/src/main.rs`
- [zed-jira](https://github.com/mulhamna/jira-commands/blob/main/crates/zed-jira/src/lib.rs): editor extension · Zed extension packaging and settings surface · `crates/zed-jira/src/lib.rs`
- [Claude plugin](https://github.com/mulhamna/jira-commands/blob/main/plugin/.claude-plugin/plugin.json): agent plugin · Plugin metadata and skills for Claude ecosystems · `plugin/.claude-plugin/plugin.json`

### Packaging

Release and installation artifacts

- [Packaging](https://github.com/mulhamna/jira-commands/blob/main/packaging/npm/package.json): distribution · npm, scoop, winget, chocolatey, and install scripts · `packaging/npm/package.json`

### Automation

Build, validation, and release pipelines

- [CI/CD](https://github.com/mulhamna/jira-commands/blob/main/.github/workflows/ci.yml): automation · GitHub workflows, release automation, and validation pipelines · `.github/workflows/ci.yml`
- [Fuzzing](https://github.com/mulhamna/jira-commands/blob/main/fuzz/fuzz_targets/markdown_adf.rs): input hardening · Markdown/ADF fuzz targets and clusterfuzzlite harness · `fuzz/fuzz_targets/markdown_adf.rs`

## Connections

- Cargo workspace → jira-core: includes · Workspace builds the shared Jira core crate
- Cargo workspace → jira: includes · Workspace builds the main CLI binary
- Cargo workspace → jira-mcp: includes · Workspace builds the MCP server
- Cargo workspace → zed-jira: includes · Workspace includes the Zed extension crate
- jira → Commands: routes · Binary dispatches into subcommand handlers
- Commands → Auth cmd: delegates · Auth subcommands are handled separately
- Commands → Issue flow: delegates · Issue operations form the primary command pipeline
- Commands → API calls: delegates · Raw API subcommands bypass higher-level issue flows
- Commands → TUI: launches · CLI can start the TUI frontend
- Issue flow → jira-core: uses · Issue commands call the shared Jira client and models
- API calls → Client: uses · Raw API path talks to the shared client
- Auth cmd → Auth: uses · CLI auth reuses profile and credential handling
- TUI → jira-core: uses · TUI reads and writes through the shared Jira layer
- TUI → Field cache: caches · TUI benefits from runtime field metadata caching
- jira-core → Client: contains · Core crate centralizes Jira HTTP access
- jira-core → Auth: contains · Core crate owns auth handling
- jira-core → Config: contains · Core crate loads profiles and deployment settings
- jira-core → ADF: contains · Core crate handles Jira document transformation
- jira-core → Field cache: contains · Core crate caches discovered fields
- jira-core → Models: contains · Core crate defines typed Jira domain models
- jira-mcp → jira-core: adapts · MCP server maps tools onto shared Jira operations
- zed-jira → jira-core: depends on · Extension mirrors the same Jira semantics via the shared core
- Claude plugin → jira-core: reflects · Plugin skills mirror the repository's Jira operations
- Packaging → jira: packages · Distribution artifacts ship the CLI frontend
- Packaging → zed-jira: packages · Distribution artifacts include the editor extension
- CI/CD → Packaging: builds · CI automates release and submission manifests
- CI/CD → jira: validates · Workflows test and release the main CLI
- CI/CD → jira-core: validates · Workflows test the shared Jira engine
- Fuzzing → ADF: hardens · Fuzzing targets markdown and ADF conversion
- Fuzzing → jira-core: hardens · Input fuzzing protects parser and transform boundaries
