# dominic-kk/halo-plugin-picbed architecture

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

- Interactive diagram: https://gitdiagram.com/dominic-kk/halo-plugin-picbed
- Repository: https://github.com/dominic-kk/halo-plugin-picbed

## Overview

Picbed is a Halo attachment-storage plugin that stores uploaded files in GitHub and serves public links through a configurable custom domain. Its main workflow is Halo policy configuration → attachment upload → generated repository object key → GitHub API write → Halo attachment metadata; deletion uses the upload-time repository, branch, and object key. The excerpts show the handler’s GitHub operations and filename generation, while README documents configuration, Secret-backed tokens, size limits, and Cloudflare-compatible links. Handler details are partial, so uncertain internal call wiring is omitted.

Main entry points: [`src/main/java/top/dominickk/picbed/provider/GitHubAttachmentHandler.java`](https://github.com/dominic-kk/halo-plugin-picbed/blob/main/src/main/java/top/dominickk/picbed/provider/GitHubAttachmentHandler.java) (Attachment handler), [`src/main/resources/extensions/setting-picbed.yaml`](https://github.com/dominic-kk/halo-plugin-picbed/blob/main/src/main/resources/extensions/setting-picbed.yaml) (Storage policy), [`src/main/java/top/dominickk/picbed/PolicyConfigWatcher.java`](https://github.com/dominic-kk/halo-plugin-picbed/blob/main/src/main/java/top/dominickk/picbed/PolicyConfigWatcher.java) (Policy watcher), [`src/main/java/top/dominickk/picbed/PicbedPlugin.java`](https://github.com/dominic-kk/halo-plugin-picbed/blob/main/src/main/java/top/dominickk/picbed/PicbedPlugin.java) (Plugin lifecycle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_policy["Policy and lifecycle"]
  node_plugin["Plugin lifecycle<br/>[PicbedPlugin.java]"]
  node_watcher["Policy watcher"]
  node_policy_config["Storage policy"]
end

subgraph group_attachment["Attachment workflow"]
  node_handler["Attachment handler"]
  node_filename["Object-key generator"]
  node_attachment_record["Halo attachment"]
end

subgraph group_github["GitHub storage"]
  node_token_secret[("Halo token Secret")]
  node_github_api["GitHub REST API"]
  node_repository[("GitHub repository")]
  node_custom_domain["Custom public domain"]
end

node_halo(("Halo administrator"))

node_plugin -->|"disposes"| node_watcher
node_halo -->|"configures"| node_policy_config
node_watcher -->|"watches changes"| node_policy_config
node_halo -->|"uploads or deletes"| node_handler
node_handler -->|"reads settings"| node_policy_config
node_handler -->|"generates object key"| node_filename
node_handler -->|"reads token"| node_token_secret
node_handler -->|"sends upload/delete requests"| node_github_api
node_github_api -->|"writes or deletes files"| node_repository
node_handler -->|"creates metadata"| node_attachment_record
node_attachment_record -->|"builds public link"| node_custom_domain

click node_plugin "https://github.com/dominic-kk/halo-plugin-picbed/blob/main/src/main/java/top/dominickk/picbed/PicbedPlugin.java"
click node_watcher "https://github.com/dominic-kk/halo-plugin-picbed/blob/main/src/main/java/top/dominickk/picbed/PolicyConfigWatcher.java"
click node_policy_config "https://github.com/dominic-kk/halo-plugin-picbed/blob/main/src/main/resources/extensions/setting-picbed.yaml"
click node_handler "https://github.com/dominic-kk/halo-plugin-picbed/blob/main/src/main/java/top/dominickk/picbed/provider/GitHubAttachmentHandler.java"
click node_filename "https://github.com/dominic-kk/halo-plugin-picbed/blob/main/src/main/java/top/dominickk/picbed/tools/FileNameGenerator.java"
click node_attachment_record "https://github.com/dominic-kk/halo-plugin-picbed/blob/main/src/main/java/top/dominickk/picbed/provider/GitHubAttachmentHandler.java"
click node_token_secret "https://github.com/dominic-kk/halo-plugin-picbed/blob/main/src/main/java/top/dominickk/picbed/provider/GitHubAttachmentHandler.java"

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_plugin,node_watcher,node_policy_config toneBlue
class node_handler,node_filename,node_attachment_record toneAmber
class node_token_secret,node_github_api,node_repository,node_custom_domain toneMint
class node_halo toneIndigo
```

## Components

### Policy and lifecycle

- [Plugin lifecycle](https://github.com/dominic-kk/halo-plugin-picbed/blob/main/src/main/java/top/dominickk/picbed/PicbedPlugin.java): `src/main/java/top/dominickk/picbed/PicbedPlugin.java`
- [Policy watcher](https://github.com/dominic-kk/halo-plugin-picbed/blob/main/src/main/java/top/dominickk/picbed/PolicyConfigWatcher.java): `src/main/java/top/dominickk/picbed/PolicyConfigWatcher.java`
- [Storage policy](https://github.com/dominic-kk/halo-plugin-picbed/blob/main/src/main/resources/extensions/setting-picbed.yaml): `src/main/resources/extensions/setting-picbed.yaml`

### Attachment workflow

- [Attachment handler](https://github.com/dominic-kk/halo-plugin-picbed/blob/main/src/main/java/top/dominickk/picbed/provider/GitHubAttachmentHandler.java): `src/main/java/top/dominickk/picbed/provider/GitHubAttachmentHandler.java`
- [Object-key generator](https://github.com/dominic-kk/halo-plugin-picbed/blob/main/src/main/java/top/dominickk/picbed/tools/FileNameGenerator.java): `src/main/java/top/dominickk/picbed/tools/FileNameGenerator.java`
- [Halo attachment](https://github.com/dominic-kk/halo-plugin-picbed/blob/main/src/main/java/top/dominickk/picbed/provider/GitHubAttachmentHandler.java): `src/main/java/top/dominickk/picbed/provider/GitHubAttachmentHandler.java`

### GitHub storage

- [Halo token Secret](https://github.com/dominic-kk/halo-plugin-picbed/blob/main/src/main/java/top/dominickk/picbed/provider/GitHubAttachmentHandler.java): `src/main/java/top/dominickk/picbed/provider/GitHubAttachmentHandler.java`
- **GitHub REST API**
- **GitHub repository**
- **Custom public domain**

### Other components

- **Halo administrator**

## Connections

- Plugin lifecycle → Policy watcher: disposes
- Halo administrator → Storage policy: configures
- Policy watcher → Storage policy: watches changes
- Halo administrator → Attachment handler: uploads or deletes
- Attachment handler → Storage policy: reads settings
- Attachment handler → Object-key generator: generates object key
- Attachment handler → Halo token Secret: reads token
- Attachment handler → GitHub REST API: sends upload/delete requests
- GitHub REST API → GitHub repository: writes or deletes files
- Attachment handler → Halo attachment: creates metadata
- Halo attachment → Custom public domain: builds public link