# gethomepage/homepage architecture

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

- Interactive diagram: https://gitdiagram.com/gethomepage/homepage
- Repository: https://github.com/gethomepage/homepage

## Overview

Homepage is a configurable self-hosted dashboard: users view service links and bookmarks, monitor integrations, and use utility widgets and search. Configuration is loaded from YAML and can include Docker label discovery; the page combines configured data with rendered components. Widget requests are served through backend APIs, which query external services while keeping credentials server-side. The README also documents themes, layouts, localization, and optional authentication. Wiring for some unsampled subsystems is represented at directory-level only; edges are limited to documented behavior and sampled call relationships.

Main entry points: [`src/pages/index.jsx`](https://github.com/gethomepage/homepage/blob/dev/src/pages/index.jsx) (Homepage page), [`src/pages/api/widgets/index.js`](https://github.com/gethomepage/homepage/blob/dev/src/pages/api/widgets/index.js) (Widget API), [`src/pages/api/services/index.js`](https://github.com/gethomepage/homepage/blob/dev/src/pages/api/services/index.js) (Services API), [`src/widgets/components.js`](https://github.com/gethomepage/homepage/blob/dev/src/widgets/components.js) (Service widgets)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["Dashboard UI"]
  node_homepage["Homepage page<br/>[index.jsx]"]
  node_service_ui["Services and bookmarks<br/>[list.jsx]"]
  node_widget_ui["Service widgets<br/>[components.js]"]
  node_info_widgets["Information widgets<br/>[widget.jsx]"]
  node_search_ui["Search and quicklaunch<br/>[quicklaunch.jsx]"]
end

subgraph group_configuration["Configuration"]
  node_settings["Settings and config<br/>[config.js]"]
  node_service_config["Service config loader<br/>[service-helpers.js]"]
  node_widget_config["Widget config loader<br/>[widget-helpers.js]"]
  node_config_api["Config API<br/>[&#91;path&#93;.js]"]
end

subgraph group_integrations["Integrations"]
  node_docker["Docker integration<br/>[docker.js]"]
  node_service_api["Services API<br/>[index.js]"]
  node_widget_api["Widget API<br/>[index.js]"]
  node_widget_proxy["Widget request proxy<br/>[use-widget-api.js]"]
  node_kube_api["Kubernetes status and stats<br/>[&#91;...service&#93;.js]"]
  node_proxmox_api["Proxmox stats<br/>[&#91;...service&#93;.js]"]
end

subgraph group_utilities["Utilities"]
  node_search_api["Search suggestions"]
end

subgraph group_security["Security"]
  node_auth_api["Optional authentication<br/>[&#91;...nextauth&#93;.js]"]
end

node_user(("Dashboard user"))
node_config_files["YAML configuration"]
node_external_services{{"Self-hosted services"}}
node_search_provider{{"Search providers"}}
node_identity_provider{{"OIDC provider"}}

node_user -->|"opens dashboard"| node_homepage
node_homepage -->|"loads settings"| node_settings
node_homepage -->|"requests services"| node_service_api
node_homepage -->|"requests widgets"| node_widget_api
node_service_api -->|"loads service config"| node_service_config
node_widget_api -->|"loads widget config"| node_widget_config
node_config_files -->|"provides settings"| node_settings
node_config_files -->|"provides services"| node_service_config
node_config_files -->|"provides widgets"| node_widget_config
node_service_config -.->|"discovers containers"| node_docker
node_service_api -->|"returns groups"| node_service_ui
node_widget_api -->|"returns definitions"| node_widget_ui
node_homepage -->|"renders groups"| node_service_ui
node_homepage -->|"renders widgets"| node_widget_ui
node_homepage -->|"renders utilities"| node_info_widgets
node_widget_ui -->|"requests widget data"| node_widget_proxy
node_widget_proxy -->|"fetches data"| node_widget_api
node_widget_api -->|"queries integrations"| node_external_services
node_kube_api -->|"queries Kubernetes"| node_external_services
node_proxmox_api -->|"queries Proxmox"| node_external_services
node_homepage -->|"loads custom assets"| node_config_api
node_homepage -->|"opens quicklaunch"| node_search_ui
node_search_ui -->|"fetches suggestions"| node_search_api
node_search_api -->|"requests suggestions"| node_search_provider
node_user -.->|"signs in"| node_auth_api
node_auth_api -.->|"authenticates with"| node_identity_provider

click node_homepage "https://github.com/gethomepage/homepage/blob/dev/src/pages/index.jsx"
click node_service_ui "https://github.com/gethomepage/homepage/blob/dev/src/components/services/list.jsx"
click node_widget_ui "https://github.com/gethomepage/homepage/blob/dev/src/widgets/components.js"
click node_info_widgets "https://github.com/gethomepage/homepage/blob/dev/src/components/widgets/widget.jsx"
click node_search_ui "https://github.com/gethomepage/homepage/blob/dev/src/components/quicklaunch.jsx"
click node_settings "https://github.com/gethomepage/homepage/blob/dev/src/utils/config/config.js"
click node_service_config "https://github.com/gethomepage/homepage/blob/dev/src/utils/config/service-helpers.js"
click node_widget_config "https://github.com/gethomepage/homepage/blob/dev/src/utils/config/widget-helpers.js"
click node_config_api "https://github.com/gethomepage/homepage/blob/dev/src/pages/api/config/%5Bpath%5D.js"
click node_docker "https://github.com/gethomepage/homepage/blob/dev/src/utils/config/docker.js"
click node_service_api "https://github.com/gethomepage/homepage/blob/dev/src/pages/api/services/index.js"
click node_widget_api "https://github.com/gethomepage/homepage/blob/dev/src/pages/api/widgets/index.js"
click node_widget_proxy "https://github.com/gethomepage/homepage/blob/dev/src/utils/proxy/use-widget-api.js"
click node_kube_api "https://github.com/gethomepage/homepage/blob/dev/src/pages/api/kubernetes/status/%5B...service%5D.js"
click node_proxmox_api "https://github.com/gethomepage/homepage/blob/dev/src/pages/api/proxmox/stats/%5B...service%5D.js"
click node_search_api "https://github.com/gethomepage/homepage/blob/dev/src/pages/api/search/searchSuggestion.js"
click node_auth_api "https://github.com/gethomepage/homepage/blob/dev/src/pages/api/auth/%5B...nextauth%5D.js"

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_homepage,node_service_ui,node_widget_ui,node_info_widgets,node_search_ui,node_user toneBlue
class node_settings,node_service_config,node_widget_config,node_config_api toneAmber
class node_docker,node_service_api,node_widget_api,node_widget_proxy,node_kube_api,node_proxmox_api toneMint
class node_search_api toneRose
class node_auth_api,node_config_files,node_external_services,node_search_provider,node_identity_provider toneIndigo
```

## Components

### Dashboard UI

- [Homepage page](https://github.com/gethomepage/homepage/blob/dev/src/pages/index.jsx): `src/pages/index.jsx`
- [Services and bookmarks](https://github.com/gethomepage/homepage/blob/dev/src/components/services/list.jsx): `src/components/services/list.jsx`
- [Service widgets](https://github.com/gethomepage/homepage/blob/dev/src/widgets/components.js): `src/widgets/components.js`
- [Information widgets](https://github.com/gethomepage/homepage/blob/dev/src/components/widgets/widget.jsx): `src/components/widgets/widget.jsx`
- [Search and quicklaunch](https://github.com/gethomepage/homepage/blob/dev/src/components/quicklaunch.jsx): `src/components/quicklaunch.jsx`

### Configuration

- [Settings and config](https://github.com/gethomepage/homepage/blob/dev/src/utils/config/config.js): `src/utils/config/config.js`
- [Service config loader](https://github.com/gethomepage/homepage/blob/dev/src/utils/config/service-helpers.js): `src/utils/config/service-helpers.js`
- [Widget config loader](https://github.com/gethomepage/homepage/blob/dev/src/utils/config/widget-helpers.js): `src/utils/config/widget-helpers.js`
- [Config API](https://github.com/gethomepage/homepage/blob/dev/src/pages/api/config/%5Bpath%5D.js): `src/pages/api/config/[path].js`

### Integrations

- [Docker integration](https://github.com/gethomepage/homepage/blob/dev/src/utils/config/docker.js): `src/utils/config/docker.js`
- [Services API](https://github.com/gethomepage/homepage/blob/dev/src/pages/api/services/index.js): `src/pages/api/services/index.js`
- [Widget API](https://github.com/gethomepage/homepage/blob/dev/src/pages/api/widgets/index.js): `src/pages/api/widgets/index.js`
- [Widget request proxy](https://github.com/gethomepage/homepage/blob/dev/src/utils/proxy/use-widget-api.js): `src/utils/proxy/use-widget-api.js`
- [Kubernetes status and stats](https://github.com/gethomepage/homepage/blob/dev/src/pages/api/kubernetes/status/%5B...service%5D.js): `src/pages/api/kubernetes/status/[...service].js`
- [Proxmox stats](https://github.com/gethomepage/homepage/blob/dev/src/pages/api/proxmox/stats/%5B...service%5D.js): `src/pages/api/proxmox/stats/[...service].js`

### Utilities

- [Search suggestions](https://github.com/gethomepage/homepage/blob/dev/src/pages/api/search/searchSuggestion.js): `src/pages/api/search/searchSuggestion.js`

### Security

- [Optional authentication](https://github.com/gethomepage/homepage/blob/dev/src/pages/api/auth/%5B...nextauth%5D.js): `src/pages/api/auth/[...nextauth].js`

### Other components

- **Dashboard user**
- **YAML configuration**
- **Self-hosted services**
- **Search providers**
- **OIDC provider**

## Connections

- Dashboard user → Homepage page: opens dashboard
- Homepage page → Settings and config: loads settings
- Homepage page → Services API: requests services
- Homepage page → Widget API: requests widgets
- Services API → Service config loader: loads service config
- Widget API → Widget config loader: loads widget config
- YAML configuration → Settings and config: provides settings
- YAML configuration → Service config loader: provides services
- YAML configuration → Widget config loader: provides widgets
- Service config loader → Docker integration: discovers containers
- Services API → Services and bookmarks: returns groups
- Widget API → Service widgets: returns definitions
- Homepage page → Services and bookmarks: renders groups
- Homepage page → Service widgets: renders widgets
- Homepage page → Information widgets: renders utilities
- Service widgets → Widget request proxy: requests widget data
- Widget request proxy → Widget API: fetches data
- Widget API → Self-hosted services: queries integrations
- Kubernetes status and stats → Self-hosted services: queries Kubernetes
- Proxmox stats → Self-hosted services: queries Proxmox
- Homepage page → Config API: loads custom assets
- Homepage page → Search and quicklaunch: opens quicklaunch
- Search and quicklaunch → Search suggestions: fetches suggestions
- Search suggestions → Search providers: requests suggestions
- Dashboard user → Optional authentication: signs in
- Optional authentication → OIDC provider: authenticates with
