# sky22333/hubproxy architecture

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

- Interactive diagram: https://gitdiagram.com/sky22333/hubproxy
- Repository: https://github.com/sky22333/hubproxy

## Overview

HubProxy is a self-hosted Go proxy for container registries and GitHub, with a Vue interface for image search, tag browsing, and offline image downloads. A typical user searches for an image, browses its tags, then requests a downloadable image archive; Docker and GitHub clients also use the service directly as a proxy. The sampled router and handlers establish the main server flow. README capabilities such as Hugging Face acceleration are retained, but their internal wiring was not sampled.

Main entry points: [`src/main.go`](https://github.com/sky22333/hubproxy/blob/main/src/main.go) (HTTP server), [`web/src/router/index.ts`](https://github.com/sky22333/hubproxy/blob/main/web/src/router/index.ts) (Page router), [`src/handlers/search.go`](https://github.com/sky22333/hubproxy/blob/main/src/handlers/search.go) (Search and tags), [`web/src/api.ts`](https://github.com/sky22333/hubproxy/blob/main/web/src/api.ts) (Browser API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_server["Server and configuration"]
  node_main["HTTP server<br/>[main.go]"]
  node_config["Configuration<br/>[config.go]"]
end

subgraph group_proxy["Proxy services"]
  node_docker["Registry proxy<br/>[docker.go]"]
  node_github["GitHub and HF proxy<br/>[github.go]"]
end

subgraph group_images["Image discovery and downloads"]
  node_search["Search and tags<br/>[search.go]"]
  node_imagetar["Image archive downloads<br/>[imagetar.go]"]
end

subgraph group_web["Web interface"]
  node_frontend["Embedded SPA routes<br/>[main.go]"]
  node_app["Vue application shell<br/>[App.vue]"]
  node_router["Page router<br/>[index.ts]"]
  node_searchpage["Search page<br/>[SearchPage.vue]"]
  node_imagespage["Offline images page<br/>[ImagesPage.vue]"]
  node_homepage["GitHub acceleration page<br/>[HomePage.vue]"]
  node_api["Browser API client<br/>[api.ts]"]
end

subgraph group_policy["Access and networking"]
  node_policy["Rate limiting and IP policy<br/>[ratelimiter.go]"]
  node_http["Outbound HTTP clients<br/>[http_client.go]"]
end

node_user(("User or client"))
node_registry{{"Container registries"}}
node_githubservice{{"GitHub and Hugging Face"}}
node_dockerhub{{"Docker Hub API"}}

node_user -->|"sends requests"| node_main
node_main -->|"loads settings"| node_config
node_main -->|"installs middleware"| node_policy
node_main -->|"routes registry traffic"| node_docker
node_main -->|"routes fallback traffic"| node_github
node_main -->|"registers download routes"| node_imagetar
node_main -->|"registers search route"| node_search
node_main -->|"serves SPA routes"| node_frontend
node_docker -->|"proxies registry requests"| node_registry
node_github -->|"accelerates file requests"| node_githubservice
node_search -->|"requests via client"| node_http
node_search -->|"fetches search and tags"| node_dockerhub
node_imagetar -->|"streams image content"| node_registry
node_main -->|"serves embedded app"| node_app
node_app -->|"renders routed view"| node_router
node_router -->|"routes search page"| node_searchpage
node_router -->|"routes download page"| node_imagespage
node_router -->|"routes acceleration page"| node_homepage
node_searchpage -->|"calls search and tags"| node_api
node_api -.->|"requests search API"| node_search
node_api -.->|"requests download API"| node_imagetar

click node_main "https://github.com/sky22333/hubproxy/blob/main/src/main.go"
click node_config "https://github.com/sky22333/hubproxy/blob/main/src/config/config.go"
click node_docker "https://github.com/sky22333/hubproxy/blob/main/src/handlers/docker.go"
click node_github "https://github.com/sky22333/hubproxy/blob/main/src/handlers/github.go"
click node_search "https://github.com/sky22333/hubproxy/blob/main/src/handlers/search.go"
click node_imagetar "https://github.com/sky22333/hubproxy/blob/main/src/handlers/imagetar.go"
click node_frontend "https://github.com/sky22333/hubproxy/blob/main/src/main.go"
click node_app "https://github.com/sky22333/hubproxy/blob/main/web/src/App.vue"
click node_router "https://github.com/sky22333/hubproxy/blob/main/web/src/router/index.ts"
click node_searchpage "https://github.com/sky22333/hubproxy/blob/main/web/src/pages/SearchPage.vue"
click node_imagespage "https://github.com/sky22333/hubproxy/blob/main/web/src/pages/ImagesPage.vue"
click node_homepage "https://github.com/sky22333/hubproxy/blob/main/web/src/pages/HomePage.vue"
click node_api "https://github.com/sky22333/hubproxy/blob/main/web/src/api.ts"
click node_policy "https://github.com/sky22333/hubproxy/blob/main/src/utils/ratelimiter.go"
click node_http "https://github.com/sky22333/hubproxy/blob/main/src/utils/http_client.go"

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_main,node_config,node_user toneBlue
class node_docker,node_github toneAmber
class node_search,node_imagetar,node_dockerhub toneMint
class node_frontend,node_app,node_router,node_searchpage,node_imagespage,node_homepage,node_api toneRose
class node_policy,node_http,node_registry,node_githubservice toneIndigo
```

## Components

### Server and configuration

- [HTTP server](https://github.com/sky22333/hubproxy/blob/main/src/main.go): `src/main.go`
- [Configuration](https://github.com/sky22333/hubproxy/blob/main/src/config/config.go): `src/config/config.go`

### Proxy services

- [Registry proxy](https://github.com/sky22333/hubproxy/blob/main/src/handlers/docker.go): `src/handlers/docker.go`
- [GitHub and HF proxy](https://github.com/sky22333/hubproxy/blob/main/src/handlers/github.go): `src/handlers/github.go`

### Image discovery and downloads

- [Search and tags](https://github.com/sky22333/hubproxy/blob/main/src/handlers/search.go): `src/handlers/search.go`
- [Image archive downloads](https://github.com/sky22333/hubproxy/blob/main/src/handlers/imagetar.go): `src/handlers/imagetar.go`

### Web interface

- [Embedded SPA routes](https://github.com/sky22333/hubproxy/blob/main/src/main.go): `src/main.go`
- [Vue application shell](https://github.com/sky22333/hubproxy/blob/main/web/src/App.vue): `web/src/App.vue`
- [Page router](https://github.com/sky22333/hubproxy/blob/main/web/src/router/index.ts): `web/src/router/index.ts`
- [Search page](https://github.com/sky22333/hubproxy/blob/main/web/src/pages/SearchPage.vue): `web/src/pages/SearchPage.vue`
- [Offline images page](https://github.com/sky22333/hubproxy/blob/main/web/src/pages/ImagesPage.vue): `web/src/pages/ImagesPage.vue`
- [GitHub acceleration page](https://github.com/sky22333/hubproxy/blob/main/web/src/pages/HomePage.vue): `web/src/pages/HomePage.vue`
- [Browser API client](https://github.com/sky22333/hubproxy/blob/main/web/src/api.ts): `web/src/api.ts`

### Access and networking

- [Rate limiting and IP policy](https://github.com/sky22333/hubproxy/blob/main/src/utils/ratelimiter.go): `src/utils/ratelimiter.go`
- [Outbound HTTP clients](https://github.com/sky22333/hubproxy/blob/main/src/utils/http_client.go): `src/utils/http_client.go`

### Other components

- **User or client**
- **Container registries**
- **GitHub and Hugging Face**
- **Docker Hub API**

## Connections

- User or client → HTTP server: sends requests (evidence: `README.md`)
- HTTP server → Configuration: loads settings (evidence: `src/main.go`)
- HTTP server → Rate limiting and IP policy: installs middleware (evidence: `src/main.go`)
- HTTP server → Registry proxy: routes registry traffic (evidence: `src/main.go`)
- HTTP server → GitHub and HF proxy: routes fallback traffic (evidence: `src/main.go`)
- HTTP server → Image archive downloads: registers download routes (evidence: `src/main.go`)
- HTTP server → Search and tags: registers search route (evidence: `src/main.go`)
- HTTP server → Embedded SPA routes: serves SPA routes (evidence: `src/main.go`)
- Registry proxy → Container registries: proxies registry requests (evidence: `README.md`)
- GitHub and HF proxy → GitHub and Hugging Face: accelerates file requests (evidence: `README.md`)
- Search and tags → Outbound HTTP clients: requests via client (evidence: `src/handlers/search.go`)
- Search and tags → Docker Hub API: fetches search and tags (evidence: `src/handlers/search.go`)
- Image archive downloads → Container registries: streams image content (evidence: `src/handlers/imagetar.go`)
- HTTP server → Vue application shell: serves embedded app (evidence: `src/main.go`)
- Vue application shell → Page router: renders routed view (evidence: `web/src/App.vue`)
- Page router → Search page: routes search page (evidence: `web/src/router/index.ts`)
- Page router → Offline images page: routes download page (evidence: `web/src/router/index.ts`)
- Page router → GitHub acceleration page: routes acceleration page (evidence: `web/src/router/index.ts`)
- Search page → Browser API client: calls search and tags (evidence: `web/src/pages/SearchPage.vue`)
- Browser API client → Search and tags: requests search API
- Browser API client → Image archive downloads: requests download API
