# mobz/elasticsearch-head architecture

> Architecture diagram of the GitHub repository mobz/elasticsearch-head, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mobz/elasticsearch-head
- Repository: https://github.com/mobz/elasticsearch-head

## Overview

##### Project type and purpose
- This is an open-source, single-page web application (“elasticsearch-head”) that provides a rich front-end GUI for inspecting and administering one or more Elasticsearch clusters.
- It can run as:
- a standalone HTTP server (Node.js + Grunt) serving static assets (port 9100)
- a Docker container (mobz/elasticsearch-head)
- a Chrome extension (`src/chrome_ext`)
- a deprecated Elasticsearch site plugin

##### File structure
- Top-level build & config:
- Gruntfile.js, Dockerfile(.alpine), package.json → build & dev server
- proxy/ → Node.js code (proxy/index.js) + cluster config (proxy/clusters/*.json) + recipes for bypassing CORS
- Core application:
- src/app/
– data/ (query, model, metadata, data–source interfaces)
– services/ (cluster discovery, cluster-state polling, user preferences)
– ui/ (widgets, panels, views, controls)
– ux/ (base classes: observable, drag-drop, templates)
– app.js + app.css → entry-point, bootstrapping
- src/chrome_ext/ → background.js + manifest.json for the Chrome extension version
- src/vendor/ → third-party libraries
- Distribution:
- _site/ → compiled static site (HTML, CSS, JS, fonts, i18n bundles)

##### README for additional insights
- Describes run modes, CORS requirements, Docker tags, special proxy mode, URL parameters for base_uri/auth/lang.
- Mentions the HTTP REST API at port 9200 exposed by Elasticsearch.
- Emphasizes single-page nature and simple static-file deployment.

##### Components & Relationships – how to represent them
1. Browser (Client): loads SPA assets, renders UI, fires HTTP requests
2. Static Server (Node.js/Grunt) or any webserver (serves `_site/` assets)
3. Local Proxy (Node.js in `proxy/`) – optional: bypasses same-origin restrictions, multiplexes to multiple clusters
4. Elasticsearch cluster(s) (REST API on port 9200)
5. Chrome Extension (background script in `src/chrome_ext`) – alternate client path
- Browser GET → Static Server (9100) → retrieves HTML/CSS/JS
- Browser (JS) → HTTP REST → Elasticsearch directly (CORS enabled)
- Browser (JS) → HTTP → Local Proxy → HTTP → one or more Elasticsearch clusters
- Chrome Extension → HTTP → Elasticsearch (no CORS)
- Presentation Layer (src/app/ui + src/app/ux)
- Application Logic / Services (src/app/services)
- Data Abstraction Layer (src/app/data)
- External Integration (proxy module, Elasticsearch REST)
d. Key technologies & frameworks:
- JavaScript, HTML5, CSS (SPA)
- Grunt (build tool), Node.js (dev server + proxy)
- Docker (containerized deployment)
- Chrome Extension APIs

##### Be exhaustive but not cluttered
- Every major subdirectory as a module if it plays a standalone role (e.g., `src/app/data`, `src/app/services/clusterState`, `proxy`).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Tier
    subgraph "Client: Browser"
        direction TB
        Browser["Browser (SPA)"]:::client
        Browser -->|"GET assets"| StaticServer
        Browser -->|"Loads SPA Entry"| AppEntry
        Browser -->|"REST API"| ESCluster
        Browser -->|"Proxy API"| LocalProxy
    end

    subgraph "SPA (src/app)" 
        direction TB

        subgraph "Presentation Layer"
            direction TB
            UIComp["UI Components"]:::ui
            click UIComp "https://github.com/mobz/elasticsearch-head/tree/master/src/app/ui/"
        end

        subgraph "UX Utilities"
            direction TB
            UX["UX Utilities"]:::ui
            click UX "https://github.com/mobz/elasticsearch-head/tree/master/src/app/ux/"
        end

        subgraph "Application Logic / Services"
            direction TB
            ClusterDiscovery["ClusterService"]:::services
            click ClusterDiscovery "https://github.com/mobz/elasticsearch-head/blob/master/src/app/services/cluster/cluster.js"
            ClusterState["ClusterStateService"]:::services
            click ClusterState "https://github.com/mobz/elasticsearch-head/blob/master/src/app/services/clusterState/clusterState.js"
            Preferences["PreferencesService"]:::services
            click Preferences "https://github.com/mobz/elasticsearch-head/blob/master/src/app/services/preferences/preferences.js"
        end

        subgraph "Data Abstraction Layer"
            direction TB
            Query["Query"]:::data
            click Query "https://github.com/mobz/elasticsearch-head/blob/master/src/app/data/query.js"
            Meta["MetaData"]:::data
            click Meta "https://github.com/mobz/elasticsearch-head/blob/master/src/app/data/metaData.js"
            DataInterface["DataSourceInterface"]:::data
            click DataInterface "https://github.com/mobz/elasticsearch-head/blob/master/src/app/data/dataSourceInterface.js"
            Model["Model"]:::data
            click Model "https://github.com/mobz/elasticsearch-head/blob/master/src/app/data/model/model.js"
        end

        AppEntry["Entry Point\napp.js / app.css"]:::entry
        click AppEntry "https://github.com/mobz/elasticsearch-head/blob/master/src/app/app.js"
    end

    subgraph "Alternate Client: Chrome Extension"
        direction TB
        ChromeExt["Chrome Extension"]:::client
        click ChromeExt "https://github.com/mobz/elasticsearch-head/blob/master/src/chrome_ext/background.js"
        ChromeExt -->|"REST API (no CORS)"| ESCluster
    end

    %% Server Tier
    subgraph "Server"
        direction TB
        StaticServer["Static Server\n(Grunt, Node.js)"]:::server
        click StaticServer "https://github.com/mobz/elasticsearch-head/blob/master/Gruntfile.js"
        LocalProxy["Local Proxy\n(proxy/index.js)"]:::server
        click LocalProxy "https://github.com/mobz/elasticsearch-head/blob/master/proxy/index.js"
        StaticServer --> Browser
        LocalProxy --> ESCluster
    end

    %% External Tier
    subgraph "External Systems"
        direction TB
        ESCluster["Elasticsearch Cluster(s)\nREST API (9200)"]:::external
    end

    %% Additional Build & Distribution
    subgraph "Build & Distribution"
        direction TB
        Gruntfile["Gruntfile.js"]:::build
        Package["package.json"]:::build
        Dockerfile["Dockerfile"]:::build
        SiteDist["_site/ (Compiled Site)"]:::build
        click Gruntfile "https://github.com/mobz/elasticsearch-head/blob/master/Gruntfile.js"
        click Package "https://github.com/mobz/elasticsearch-head/blob/master/package.json"
        click Dockerfile "https://github.com/mobz/elasticsearch-head/tree/master/Dockerfile"
        click SiteDist "https://github.com/mobz/elasticsearch-head/tree/master/_site/"
        Gruntfile --> StaticServer
        Package --> StaticServer
        Dockerfile --> StaticServer
        SiteDist --> StaticServer
    end

    %% Styles
    classDef client fill:#cce5ff,stroke:#004085,color:#004085;
    classDef ui fill:#b3d7ff,stroke:#005cbf,color:#005cbf;
    classDef services fill:#d4edda,stroke:#155724,color:#155724;
    classDef data fill:#ffe5b4,stroke:#d39e00,color:#d39e00;
    classDef entry fill:#cce5ff,stroke:#004085,color:#004085,stroke-dasharray: 5 5;
    classDef server fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef external fill:#f8d7da,stroke:#721c24,color:#721c24;
    classDef build fill:#d1ecf1,stroke:#0c5460,color:#0c5460;
```
