# yellowback/forgejo-claude-code-action architecture

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

- Interactive diagram: https://gitdiagram.com/yellowback/forgejo-claude-code-action
- Repository: https://github.com/yellowback/forgejo-claude-code-action

## Overview

Claude Code Action turns GitHub or Forgejo issue/PR activity into a Claude run, with modes for mention-driven or automated execution. The main path parses the event, checks triggering and permissions, gathers platform context, builds a prompt, and runs Claude; follow-up entrypoints manage comment links and progress. The README also documents code review, implementation, GitHub/file tools, and multiple authentication providers. Source excerpts show orchestration and fetch/prompt behavior, but not all runtime integrations, so uncertain links are omitted.

Main entry points: [`src/entrypoints/prepare.ts`](https://github.com/yellowback/forgejo-claude-code-action/blob/forgejo/src/entrypoints/prepare.ts) (Prepare run), [`src/mcp/install-mcp-server.ts`](https://github.com/yellowback/forgejo-claude-code-action/blob/forgejo/src/mcp/install-mcp-server.ts) (MCP installation), [`src/platform/data-fetcher.ts`](https://github.com/yellowback/forgejo-claude-code-action/blob/forgejo/src/platform/data-fetcher.ts) (Platform data fetch), [`src/forgejo/api/rest-adapter.ts`](https://github.com/yellowback/forgejo-claude-code-action/blob/forgejo/src/forgejo/api/rest-adapter.ts) (Platform client adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Event workflow"]
  node_prepare["Prepare run<br/>[prepare.ts]"]
  node_context["Parse event context<br/>[context.ts]"]
  node_mode["Execution modes<br/>[registry.ts]"]
  node_trigger["Trigger checks<br/>[index.ts]"]
  node_permissions["Actor permissions<br/>[permissions.ts]"]
  node_comments["Comment lifecycle<br/>[create-initial.ts]"]
  node_branch["Branch operations<br/>[branch.ts]"]
  node_followup["Comment-link update"]
end

subgraph group_platform["Platform integration"]
  node_github_fetch["GitHub data fetch<br/>[fetcher.ts]"]
  node_platform_fetch["Platform data fetch<br/>[data-fetcher.ts]"]
  node_platform_client["Platform client adapter<br/>[rest-adapter.ts]"]
  node_forgejo_api["Forgejo API<br/>[client.ts]"]
  node_github_api["GitHub API client<br/>[client.ts]"]
end

subgraph group_assistant["Claude execution"]
  node_prompt["Prompt assembly<br/>[index.ts]"]
  node_runner["Claude runner<br/>[run-claude.ts]"]
  node_action["Action entry<br/>[index.ts]"]
  node_progress["Turn formatting<br/>[format-turns.ts]"]
end

subgraph group_tools["Assistant tools"]
  node_mcp_install["MCP installation"]
  node_actions_tool["GitHub Actions tools"]
  node_comment_tool["GitHub comment tools"]
  node_file_tool["GitHub file tools"]
end

node_user(("Repository user"))
node_github["GitHub"]
node_forgejo["Forgejo"]

node_user -->|"triggers workflow"| node_prepare
node_prepare -->|"parses event"| node_context
node_context -->|"validates mode"| node_mode
node_mode -->|"selects tag mode"| node_trigger
node_prepare -->|"checks actor"| node_permissions
node_prepare -->|"fetches context"| node_github_fetch
node_prepare -->|"fetches platform data"| node_platform_fetch
node_platform_fetch -->|"creates client"| node_platform_client
node_platform_client -.->|"uses Forgejo API"| node_forgejo_api
node_platform_client -.->|"uses GitHub API"| node_github_api
node_github_fetch -->|"queries API"| node_github_api
node_platform_fetch -.->|"requests data"| node_github
node_forgejo_api -->|"requests data"| node_forgejo
node_prepare -->|"creates initial comment"| node_comments
node_prepare -->|"sets up branch"| node_branch
node_prepare -->|"installs tools"| node_mcp_install
node_prompt -->|"formats fetched data"| node_github_fetch
node_prepare -->|"generates prompt"| node_prompt
node_action -->|"runs Claude"| node_runner
node_runner -.->|"uses configured provider"| node_github
node_prepare -.->|"updates later"| node_followup
node_followup -->|"updates comment"| node_comments
node_mcp_install -.->|"registers tool"| node_actions_tool
node_mcp_install -.->|"registers tool"| node_comment_tool
node_mcp_install -->|"registers tool"| node_file_tool
node_runner -.->|"formats turns"| node_progress

click node_prepare "https://github.com/yellowback/forgejo-claude-code-action/blob/forgejo/src/entrypoints/prepare.ts"
click node_context "https://github.com/yellowback/forgejo-claude-code-action/blob/forgejo/src/github/context.ts"
click node_mode "https://github.com/yellowback/forgejo-claude-code-action/blob/forgejo/src/modes/registry.ts"
click node_trigger "https://github.com/yellowback/forgejo-claude-code-action/blob/forgejo/src/modes/tag/index.ts"
click node_permissions "https://github.com/yellowback/forgejo-claude-code-action/blob/forgejo/src/github/validation/permissions.ts"
click node_prompt "https://github.com/yellowback/forgejo-claude-code-action/blob/forgejo/src/create-prompt/index.ts"
click node_runner "https://github.com/yellowback/forgejo-claude-code-action/blob/forgejo/base-action/src/run-claude.ts"
click node_action "https://github.com/yellowback/forgejo-claude-code-action/blob/forgejo/base-action/src/index.ts"
click node_github_fetch "https://github.com/yellowback/forgejo-claude-code-action/blob/forgejo/src/github/data/fetcher.ts"
click node_platform_fetch "https://github.com/yellowback/forgejo-claude-code-action/blob/forgejo/src/platform/data-fetcher.ts"
click node_platform_client "https://github.com/yellowback/forgejo-claude-code-action/blob/forgejo/src/forgejo/api/rest-adapter.ts"
click node_forgejo_api "https://github.com/yellowback/forgejo-claude-code-action/blob/forgejo/src/forgejo/api/client.ts"
click node_github_api "https://github.com/yellowback/forgejo-claude-code-action/blob/forgejo/src/github/api/client.ts"
click node_comments "https://github.com/yellowback/forgejo-claude-code-action/blob/forgejo/src/github/operations/comments/create-initial.ts"
click node_branch "https://github.com/yellowback/forgejo-claude-code-action/blob/forgejo/src/github/operations/branch.ts"
click node_followup "https://github.com/yellowback/forgejo-claude-code-action/blob/forgejo/src/entrypoints/update-comment-link.ts"
click node_mcp_install "https://github.com/yellowback/forgejo-claude-code-action/blob/forgejo/src/mcp/install-mcp-server.ts"
click node_actions_tool "https://github.com/yellowback/forgejo-claude-code-action/blob/forgejo/src/mcp/github-actions-server.ts"
click node_comment_tool "https://github.com/yellowback/forgejo-claude-code-action/blob/forgejo/src/mcp/github-comment-server.ts"
click node_file_tool "https://github.com/yellowback/forgejo-claude-code-action/blob/forgejo/src/mcp/github-file-ops-server.ts"
click node_progress "https://github.com/yellowback/forgejo-claude-code-action/blob/forgejo/src/entrypoints/format-turns.ts"

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_prepare,node_context,node_mode,node_trigger,node_permissions,node_comments,node_branch,node_followup,node_user toneBlue
class node_github_fetch,node_platform_fetch,node_platform_client,node_forgejo_api,node_github_api toneAmber
class node_prompt,node_runner,node_action,node_progress toneMint
class node_mcp_install,node_actions_tool,node_comment_tool,node_file_tool toneRose
class node_github,node_forgejo toneIndigo
```

## Components

### Event workflow

- [Prepare run](https://github.com/yellowback/forgejo-claude-code-action/blob/forgejo/src/entrypoints/prepare.ts): `src/entrypoints/prepare.ts`
- [Parse event context](https://github.com/yellowback/forgejo-claude-code-action/blob/forgejo/src/github/context.ts): `src/github/context.ts`
- [Execution modes](https://github.com/yellowback/forgejo-claude-code-action/blob/forgejo/src/modes/registry.ts): `src/modes/registry.ts`
- [Trigger checks](https://github.com/yellowback/forgejo-claude-code-action/blob/forgejo/src/modes/tag/index.ts): `src/modes/tag/index.ts`
- [Actor permissions](https://github.com/yellowback/forgejo-claude-code-action/blob/forgejo/src/github/validation/permissions.ts): `src/github/validation/permissions.ts`
- [Comment lifecycle](https://github.com/yellowback/forgejo-claude-code-action/blob/forgejo/src/github/operations/comments/create-initial.ts): `src/github/operations/comments/create-initial.ts`
- [Branch operations](https://github.com/yellowback/forgejo-claude-code-action/blob/forgejo/src/github/operations/branch.ts): `src/github/operations/branch.ts`
- [Comment-link update](https://github.com/yellowback/forgejo-claude-code-action/blob/forgejo/src/entrypoints/update-comment-link.ts): `src/entrypoints/update-comment-link.ts`

### Platform integration

- [GitHub data fetch](https://github.com/yellowback/forgejo-claude-code-action/blob/forgejo/src/github/data/fetcher.ts): `src/github/data/fetcher.ts`
- [Platform data fetch](https://github.com/yellowback/forgejo-claude-code-action/blob/forgejo/src/platform/data-fetcher.ts): `src/platform/data-fetcher.ts`
- [Platform client adapter](https://github.com/yellowback/forgejo-claude-code-action/blob/forgejo/src/forgejo/api/rest-adapter.ts): `src/forgejo/api/rest-adapter.ts`
- [Forgejo API](https://github.com/yellowback/forgejo-claude-code-action/blob/forgejo/src/forgejo/api/client.ts): `src/forgejo/api/client.ts`
- [GitHub API client](https://github.com/yellowback/forgejo-claude-code-action/blob/forgejo/src/github/api/client.ts): `src/github/api/client.ts`

### Claude execution

- [Prompt assembly](https://github.com/yellowback/forgejo-claude-code-action/blob/forgejo/src/create-prompt/index.ts): `src/create-prompt/index.ts`
- [Claude runner](https://github.com/yellowback/forgejo-claude-code-action/blob/forgejo/base-action/src/run-claude.ts): `base-action/src/run-claude.ts`
- [Action entry](https://github.com/yellowback/forgejo-claude-code-action/blob/forgejo/base-action/src/index.ts): `base-action/src/index.ts`
- [Turn formatting](https://github.com/yellowback/forgejo-claude-code-action/blob/forgejo/src/entrypoints/format-turns.ts): `src/entrypoints/format-turns.ts`

### Assistant tools

- [MCP installation](https://github.com/yellowback/forgejo-claude-code-action/blob/forgejo/src/mcp/install-mcp-server.ts): `src/mcp/install-mcp-server.ts`
- [GitHub Actions tools](https://github.com/yellowback/forgejo-claude-code-action/blob/forgejo/src/mcp/github-actions-server.ts): `src/mcp/github-actions-server.ts`
- [GitHub comment tools](https://github.com/yellowback/forgejo-claude-code-action/blob/forgejo/src/mcp/github-comment-server.ts): `src/mcp/github-comment-server.ts`
- [GitHub file tools](https://github.com/yellowback/forgejo-claude-code-action/blob/forgejo/src/mcp/github-file-ops-server.ts): `src/mcp/github-file-ops-server.ts`

### Other components

- **Repository user**
- **GitHub**
- **Forgejo**

## Connections

- Repository user → Prepare run: triggers workflow (evidence: `README.md`)
- Prepare run → Parse event context: parses event (evidence: `src/entrypoints/prepare.ts`)
- Parse event context → Execution modes: validates mode (evidence: `src/github/context.ts`)
- Execution modes → Trigger checks: selects tag mode (evidence: `src/modes/registry.ts`)
- Prepare run → Actor permissions: checks actor (evidence: `src/entrypoints/prepare.ts`)
- Prepare run → GitHub data fetch: fetches context (evidence: `src/entrypoints/prepare.ts`)
- Prepare run → Platform data fetch: fetches platform data (evidence: `src/entrypoints/prepare.ts`)
- Platform data fetch → Platform client adapter: creates client (evidence: `src/platform/data-fetcher.ts`)
- Platform client adapter → Forgejo API: uses Forgejo API (evidence: `src/forgejo/api/rest-adapter.ts`)
- Platform client adapter → GitHub API client: uses GitHub API (evidence: `src/forgejo/api/rest-adapter.ts`)
- GitHub data fetch → GitHub API client: queries API (evidence: `src/github/data/fetcher.ts`)
- Platform data fetch → GitHub: requests data
- Forgejo API → Forgejo: requests data (evidence: `src/forgejo/api/client.ts`)
- Prepare run → Comment lifecycle: creates initial comment (evidence: `src/entrypoints/prepare.ts`)
- Prepare run → Branch operations: sets up branch (evidence: `src/entrypoints/prepare.ts`)
- Prepare run → MCP installation: installs tools (evidence: `src/entrypoints/prepare.ts`)
- Prompt assembly → GitHub data fetch: formats fetched data (evidence: `src/create-prompt/index.ts`)
- Prepare run → Prompt assembly: generates prompt (evidence: `src/entrypoints/prepare.ts`)
- Action entry → Claude runner: runs Claude (evidence: `base-action/src/index.ts`)
- Claude runner → GitHub: uses configured provider
- Prepare run → Comment-link update: updates later
- Comment-link update → Comment lifecycle: updates comment (evidence: `src/entrypoints/update-comment-link.ts`)
- MCP installation → GitHub Actions tools: registers tool (evidence: `src/mcp/install-mcp-server.ts`)
- MCP installation → GitHub comment tools: registers tool
- MCP installation → GitHub file tools: registers tool (evidence: `src/mcp/install-mcp-server.ts`)
- Claude runner → Turn formatting: formats turns