# gurucomputing/headscale-ui architecture

> Architecture diagram of the GitHub repository gurucomputing/headscale-ui, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gurucomputing/headscale-ui
- Repository: https://github.com/gurucomputing/headscale-ui

## Overview

##### Project type and purpose
- This is a single-page application (SPA) “web frontend” for the Headscale coordination server.
- It is implemented in Svelte + Vite + Tailwind, packaged as a static site and served from the `/web` mount via a reverse proxy (e.g., Caddy).
- It communicates via REST/HTTP to the Headscale backend (the Tailscale-compatible server).

##### File structure
- Top-level dirs:
- `src/` – Svelte app, components organized by feature (common, devices, users, settings).
- `routes/` – SvelteKit (or Vite) route definitions and layouts.
- `docker/` – Dockerfiles and scripts for development & production images.
- `.github/workflows/` – CI/CD pipelines for publishing dev and release container images.
- `documentation/` – MD files describing architecture, configuration, development, testing, style.
- Config files: `Caddyfile`, `vite.config.js`, `tailwind.config.cjs`, `svelte.config.js`, plus `.npmrc`, Prettier, etc.

##### README for additional insights
- Confirms it is packaged as a static site, expecting to be reverse-proxied under `/web`.
- Describes Docker compose integration with Headscale server; emphasizes CORS requirements.
- References `documentation/architecture.md` for more details on design.

a. Main Components
- Client (Browser) – runs the Svelte SPA.
- Reverse Proxy (Caddy / Traefik) – serves static UI files on `/web`, proxies API calls.
- Headscale-UI Container – serves the UI on ports 8080/8443 (static assets + SPA engine).
- Headscale Server Container – the actual coordination server (API endpoints).
- Docker Registry / GitHub Container Registry – stores built images.
- CI/CD (GitHub Actions) – builds & publishes images (dev & release).
- Developer Workstation / Dev Container – local development VS Code Server, live reload.

b. Relationships & Interactions
- User → HTTP(S) Request → Reverse Proxy `/web` → Headscale-UI Container → serves `index.html` + JS/CSS.
- Browser → API calls (e.g., `/api/devices`, `/api/users`) → Reverse Proxy → Headscale Server → JSON response → Browser.
- Git Push → GitHub Actions → Build Docker images → Push to Registry → (automated) Deploy to Prod.
- Dev: mount local source into Dev Container → live rebuild on file change → browser reload.

c. Architectural Patterns & Principles
- SPA served as static assets + client-side routing.
- API Gateway / Reverse Proxy pattern (Caddy handles static + dynamic routes, CORS fixes).
- Containerization for consistency between dev & prod.
- CI/CD pipelines for automated image builds & releases.
- Feature-based component organization in Svelte (common, devices, users, settings).

d. Key Technologies & Frameworks
- Svelte + SvelteKit or Vite for the frontend.
- Tailwind CSS for utility-first styling.
- Docker (multi-stage builds) for dev & prod images.
- Caddy (or Traefik) as reverse proxy with CORS injection.
- GitHub Actions for CI/CD.
- GitHub Container Registry (ghcr.io) as Docker registry.

##### Essential Elements to Capture
- Browser → Reverse Proxy path routing `/web` vs. API path.
- CORS handling block within the proxy.
- Ports mapping: 80/443 (external) → 8080/8443 (UI) → 8080 (Headscale API).
- Local dev container mapping vs. production container mapping.
- CI workflows: publish-dev-image.yaml & publish-release.yaml.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Client
    Browser["Browser (SPA Client)"]:::frontend
    click Browser "https://github.com/gurucomputing/headscale-ui/blob/master/src/app.html"

    %% Reverse Proxy
    Proxy["Reverse Proxy (Caddy/Traefik)"]:::infra
    click Proxy "https://github.com/gurucomputing/headscale-ui/tree/master/Caddyfile"

    %% Production Containers
    subgraph "Production Environment"
        direction TB
        UIContainer["Headscale-UI Container\n(Static SPA Server)"]:::frontend
        click UIContainer "https://github.com/gurucomputing/headscale-ui/tree/master/docker/production/dockerfile"
        APIServer["Headscale Server Container\n(API Endpoints)"]:::backend
    end

    %% Development Environment
    subgraph "Development Environment"
        direction TB
        DevWorkstation["Developer Workstation\n(VS Code / Docker)"]:::infra
        DevContainer["Dev Container\n(Live Reload)"]:::frontend
        click DevContainer "https://github.com/gurucomputing/headscale-ui/tree/master/docker/development/dockerfile"
        click DevContainer "https://github.com/gurucomputing/headscale-ui/tree/master/docker/development/scripts/"
    end

    %% CI/CD and Registry
    subgraph "CI/CD & Registry"
        direction TB
        GitHub["GitHub Repo"]:::cicd
        Actions["GitHub Actions\n(publish-dev-image.yaml,\npublish-release.yaml)"]:::cicd
        click Actions "https://github.com/gurucomputing/headscale-ui/blob/master/ .github/workflows/publish-dev-image.yaml"
        click Actions "https://github.com/gurucomputing/headscale-ui/blob/master/ .github/workflows/publish-release.yaml"
        Registry["Container Registry\n(ghcr.io)"]:::cicd
    end

    %% Static Assets and Config
    subgraph "SPA Source"
        direction TB
        Core["SPA Core Files"]:::frontend
        click Core "https://github.com/gurucomputing/headscale-ui/blob/master/src/app.html"
        click Core "https://github.com/gurucomputing/headscale-ui/blob/master/src/app.css"
        click Core "https://github.com/gurucomputing/headscale-ui/blob/master/src/app.d.ts"
        Common["Common Components"]:::frontend
        click Common "https://github.com/gurucomputing/headscale-ui/tree/master/src/lib/common/"
        Devices["Devices Components"]:::frontend
        click Devices "https://github.com/gurucomputing/headscale-ui/tree/master/src/lib/devices/"
        Users["Users Components"]:::frontend
        click Users "https://github.com/gurucomputing/headscale-ui/tree/master/src/lib/users/"
        Settings["Settings Components"]:::frontend
        click Settings "https://github.com/gurucomputing/headscale-ui/tree/master/src/lib/settings/"
        Routes["Client-side Routing"]:::frontend
        click Routes "https://github.com/gurucomputing/headscale-ui/tree/master/src/routes/"
        Tailwind["Tailwind Config"]:::frontend
        click Tailwind "https://github.com/gurucomputing/headscale-ui/blob/master/tailwind.config.cjs"
        Vite["Vite Config"]:::frontend
        click Vite "https://github.com/gurucomputing/headscale-ui/blob/master/vite.config.js"
        SvelteCfg["Svelte Config"]:::frontend
        click SvelteCfg "https://github.com/gurucomputing/headscale-ui/blob/master/svelte.config.js"
    end

    %% Documentation
    subgraph "Documentation"
        direction TB
        ArchDoc["Architecture Doc"]:::infra
        click ArchDoc "https://github.com/gurucomputing/headscale-ui/blob/master/documentation/architecture.md"
        ConfigDoc["Configuration Doc"]:::infra
        click ConfigDoc "https://github.com/gurucomputing/headscale-ui/blob/master/documentation/configuration.md"
        DevDoc["Development Doc"]:::infra
        click DevDoc "https://github.com/gurucomputing/headscale-ui/blob/master/documentation/development.md"
        TestDoc["Testing Doc"]:::infra
        click TestDoc "https://github.com/gurucomputing/headscale-ui/blob/master/documentation/testing.md"
        StyleDoc["Style Guide"]:::infra
        click StyleDoc "https://github.com/gurucomputing/headscale-ui/blob/master/documentation/style.md"
    end

    %% Flows
    Browser -->|"GET /web"| Proxy
    Proxy -->|"serves static"| UIContainer
    Browser -->|"/api/*"| Proxy
    Proxy -->|"forwards API"| APIServer
    UIContainer -->|static assets| Browser
    APIServer -->|JSON response| Browser

    DevWorkstation -->|mounts source| DevContainer
    DevContainer -->|live rebuild| Browser

    GitHub -->|push| Actions
    Actions -->|build & push| Registry
    Registry -->|deploy| UIContainer
    Registry -->|deploy| APIServer

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#036,stroke-width:1px
    classDef backend fill:#98FB98,stroke:#060,stroke-width:1px
    classDef infra fill:#D3D3D3,stroke:#555,stroke-width:1px
    classDef cicd fill:#FFA500,stroke:#A65,stroke-width:1px
```
