# fabianschurig/bitbucket-cli architecture

> Architecture diagram of the GitHub repository fabianschurig/bitbucket-cli, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fabianschurig/bitbucket-cli
- Repository: https://github.com/fabianschurig/bitbucket-cli

## Overview

bitbucket-cli exposes Bitbucket Cloud operations through three user-facing products: a terminal CLI, an MCP server for agents, and a Terraform provider. The CLI and MCP workflows dispatch operations to Bitbucket; Terraform maps operations to infrastructure resources and data sources. Shared runtime layers handle request dispatch and authentication. The README documents broad generated endpoint coverage; only selected runtime paths were sampled, so uncertain internal links are omitted.

Main entry points: [`internal/client/auth.go`](https://github.com/fabianschurig/bitbucket-cli/blob/main/internal/client/auth.go) (HTTP client), [`cmd/bb-mcp/main.go`](https://github.com/fabianschurig/bitbucket-cli/blob/main/cmd/bb-mcp/main.go) (MCP entry), [`internal/tfprovider/provider.go`](https://github.com/fabianschurig/bitbucket-cli/blob/main/internal/tfprovider/provider.go) (Provider runtime), [`internal/commands`](https://github.com/fabianschurig/bitbucket-cli/tree/main/internal/commands) (CLI operations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_cli["CLI entry<br/>[main.go]"]
  node_cli_commands["CLI operations"]
end

subgraph group_shared["Shared API runtime"]
  node_repo_context["Repo context<br/>[gitcontext.go]"]
  node_dispatch["Request dispatch<br/>[dispatch.go]"]
  node_infer["Context inference<br/>[infer.go]"]
  node_client["HTTP client<br/>[auth.go]"]
  node_retry["Retry policy<br/>[retry.go]"]
end

subgraph group_mcp["MCP server"]
  node_mcp_entry["MCP entry<br/>[main.go]"]
  node_mcp_config["MCP configuration<br/>[config.go]"]
  node_mcp_registry["Tool registration<br/>[registry.go]"]
  node_mcp_tools["Generated tools"]
  node_mcp_handler["Tool handler<br/>[handler.go]"]
  node_mcp_prompts["Agent prompts<br/>[prompts.go]"]
end

subgraph group_terraform["Terraform provider"]
  node_tf_entry["Provider entry<br/>[main.go]"]
  node_tf_provider["Provider runtime<br/>[provider.go]"]
  node_tf_resources["Resources<br/>[resource.go]"]
  node_tf_datasources["Data sources<br/>[datasource.go]"]
  node_tf_operations["Generated operations"]
end

node_engineer(("Engineer"))
node_agent(("AI agent"))
node_iac_user(("Terraform user"))
node_bitbucket["Bitbucket Cloud"]

node_engineer -->|"runs"| node_cli
node_cli -->|"registers"| node_cli_commands
node_cli_commands -->|"infers defaults"| node_repo_context
node_cli_commands -->|"dispatches request"| node_dispatch
node_repo_context -->|"returns defaults"| node_cli_commands
node_dispatch -->|"infers parameters"| node_infer
node_dispatch -->|"executes request"| node_client
node_client -->|"uses retries"| node_retry
node_client -->|"sends API request"| node_bitbucket
node_agent -->|"calls tools"| node_mcp_entry
node_mcp_entry -->|"loads settings"| node_mcp_config
node_mcp_entry -->|"registers tools"| node_mcp_registry
node_mcp_registry -->|"registers groups"| node_mcp_tools
node_mcp_entry -->|"registers prompts"| node_mcp_prompts
node_mcp_tools -->|"handles tool calls"| node_mcp_handler
node_mcp_handler -->|"dispatches request"| node_dispatch
node_iac_user -->|"uses provider"| node_tf_entry
node_tf_entry -->|"starts provider"| node_tf_provider
node_tf_provider -->|"provides resources"| node_tf_resources
node_tf_provider -->|"provides data sources"| node_tf_datasources
node_tf_provider -->|"uses definitions"| node_tf_operations
node_tf_resources -->|"calls API runtime"| node_client
node_tf_datasources -->|"calls API runtime"| node_client

click node_cli "https://github.com/fabianschurig/bitbucket-cli/blob/main/cmd/bb-cli/main.go"
click node_cli_commands "https://github.com/fabianschurig/bitbucket-cli/tree/main/internal/commands"
click node_repo_context "https://github.com/fabianschurig/bitbucket-cli/blob/main/internal/gitcontext/gitcontext.go"
click node_dispatch "https://github.com/fabianschurig/bitbucket-cli/blob/main/internal/handlers/dispatch.go"
click node_infer "https://github.com/fabianschurig/bitbucket-cli/blob/main/internal/handlers/infer.go"
click node_client "https://github.com/fabianschurig/bitbucket-cli/blob/main/internal/client/auth.go"
click node_retry "https://github.com/fabianschurig/bitbucket-cli/blob/main/internal/client/retry.go"
click node_mcp_entry "https://github.com/fabianschurig/bitbucket-cli/blob/main/cmd/bb-mcp/main.go"
click node_mcp_config "https://github.com/fabianschurig/bitbucket-cli/blob/main/internal/config/config.go"
click node_mcp_registry "https://github.com/fabianschurig/bitbucket-cli/blob/main/internal/mcptools/registry.go"
click node_mcp_tools "https://github.com/fabianschurig/bitbucket-cli/tree/main/internal/mcptools"
click node_mcp_handler "https://github.com/fabianschurig/bitbucket-cli/blob/main/internal/mcptools/handler.go"
click node_mcp_prompts "https://github.com/fabianschurig/bitbucket-cli/blob/main/internal/prompts/prompts.go"
click node_tf_entry "https://github.com/fabianschurig/bitbucket-cli/blob/main/cmd/bb-tf/main.go"
click node_tf_provider "https://github.com/fabianschurig/bitbucket-cli/blob/main/internal/tfprovider/provider.go"
click node_tf_resources "https://github.com/fabianschurig/bitbucket-cli/blob/main/internal/tfprovider/resource.go"
click node_tf_datasources "https://github.com/fabianschurig/bitbucket-cli/blob/main/internal/tfprovider/datasource.go"
click node_tf_operations "https://github.com/fabianschurig/bitbucket-cli/tree/main/internal/tfprovider"

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_cli,node_cli_commands,node_iac_user toneBlue
class node_repo_context,node_dispatch,node_infer,node_client,node_retry toneAmber
class node_mcp_entry,node_mcp_config,node_mcp_registry,node_mcp_tools,node_mcp_handler,node_mcp_prompts toneMint
class node_tf_entry,node_tf_provider,node_tf_resources,node_tf_datasources,node_tf_operations toneRose
class node_engineer,node_agent,node_bitbucket toneIndigo
```

## Components

### User interfaces

- [CLI entry](https://github.com/fabianschurig/bitbucket-cli/blob/main/cmd/bb-cli/main.go): `cmd/bb-cli/main.go`
- [CLI operations](https://github.com/fabianschurig/bitbucket-cli/tree/main/internal/commands): `internal/commands`

### Shared API runtime

- [Repo context](https://github.com/fabianschurig/bitbucket-cli/blob/main/internal/gitcontext/gitcontext.go): `internal/gitcontext/gitcontext.go`
- [Request dispatch](https://github.com/fabianschurig/bitbucket-cli/blob/main/internal/handlers/dispatch.go): `internal/handlers/dispatch.go`
- [Context inference](https://github.com/fabianschurig/bitbucket-cli/blob/main/internal/handlers/infer.go): `internal/handlers/infer.go`
- [HTTP client](https://github.com/fabianschurig/bitbucket-cli/blob/main/internal/client/auth.go): `internal/client/auth.go`
- [Retry policy](https://github.com/fabianschurig/bitbucket-cli/blob/main/internal/client/retry.go): `internal/client/retry.go`

### MCP server

- [MCP entry](https://github.com/fabianschurig/bitbucket-cli/blob/main/cmd/bb-mcp/main.go): `cmd/bb-mcp/main.go`
- [MCP configuration](https://github.com/fabianschurig/bitbucket-cli/blob/main/internal/config/config.go): `internal/config/config.go`
- [Tool registration](https://github.com/fabianschurig/bitbucket-cli/blob/main/internal/mcptools/registry.go): `internal/mcptools/registry.go`
- [Generated tools](https://github.com/fabianschurig/bitbucket-cli/tree/main/internal/mcptools): `internal/mcptools`
- [Tool handler](https://github.com/fabianschurig/bitbucket-cli/blob/main/internal/mcptools/handler.go): `internal/mcptools/handler.go`
- [Agent prompts](https://github.com/fabianschurig/bitbucket-cli/blob/main/internal/prompts/prompts.go): `internal/prompts/prompts.go`

### Terraform provider

- [Provider entry](https://github.com/fabianschurig/bitbucket-cli/blob/main/cmd/bb-tf/main.go): `cmd/bb-tf/main.go`
- [Provider runtime](https://github.com/fabianschurig/bitbucket-cli/blob/main/internal/tfprovider/provider.go): `internal/tfprovider/provider.go`
- [Resources](https://github.com/fabianschurig/bitbucket-cli/blob/main/internal/tfprovider/resource.go): `internal/tfprovider/resource.go`
- [Data sources](https://github.com/fabianschurig/bitbucket-cli/blob/main/internal/tfprovider/datasource.go): `internal/tfprovider/datasource.go`
- [Generated operations](https://github.com/fabianschurig/bitbucket-cli/tree/main/internal/tfprovider): `internal/tfprovider`

### Other components

- **Engineer**
- **AI agent**
- **Terraform user**
- **Bitbucket Cloud**

## Connections

- Engineer → CLI entry: runs
- CLI entry → CLI operations: registers
- CLI operations → Repo context: infers defaults
- CLI operations → Request dispatch: dispatches request
- Repo context → CLI operations: returns defaults
- Request dispatch → Context inference: infers parameters
- Request dispatch → HTTP client: executes request
- HTTP client → Retry policy: uses retries
- HTTP client → Bitbucket Cloud: sends API request
- AI agent → MCP entry: calls tools
- MCP entry → MCP configuration: loads settings
- MCP entry → Tool registration: registers tools
- Tool registration → Generated tools: registers groups
- MCP entry → Agent prompts: registers prompts
- Generated tools → Tool handler: handles tool calls
- Tool handler → Request dispatch: dispatches request
- Terraform user → Provider entry: uses provider
- Provider entry → Provider runtime: starts provider
- Provider runtime → Resources: provides resources
- Provider runtime → Data sources: provides data sources
- Provider runtime → Generated operations: uses definitions
- Resources → HTTP client: calls API runtime
- Data sources → HTTP client: calls API runtime