elastichq/elasticsearch-hq

1. ElasticHQ is a two-tier application: a Python backend serves the API and HTML shell, and a JavaScript single-page UI provides the operator console. The system’s purpose is to monitor and administer one or more Elasticsearch clusters.

2. The primary external dependency is Elasticsearch itself. The backend talks to remote clusters for cluster state, node stats, indices, snapshots, queries, and diagnostics; the UI never talks directly to Elasticsearch and instead uses ElasticHQ’s HTTP API.

3. The backend entrypoints are application.py and manage.py, with production process configs in deployment/ for Gunicorn, logging, and Supervisor. This suggests a Flask-style web server packaging that can run standalone, behind a process manager, or inside Docker/OpenShift.

4. Backend routing is organized under elastichq/api/. These modules split the HTTP surface by domain: clusters, nodes, indices, snapshots, diagnostics, query, status, REST passthrough, and a socket endpoint. endpoints.py and hq.py look like shared routing/landing-page concerns.

5. The backend service layer in elastichq/service/ is the core orchestration boundary. It contains per-domain services such as ClusterService, NodeService, IndicesService, SnapshotService, QueryService, DiagnosticsService, HQService, plus ConnectionService for Elasticsearch connectivity. This layer likely transforms ES responses into UI-friendly payloads and centralizes business rules.

6. Persistence is separate from live cluster access. elastichq/service/persistence/ClusterDBService.py and the migrations/ directory indicate a small local database for saved cluster definitions/settings, with Alembic-managed schema changes. Live cluster metrics remain ephemeral and are fetched from Elasticsearch on demand.

7. Background or asynchronous work is modeled explicitly in elastichq/common/JobPool.py, TaskPool.py, and model/Task.py. That implies some operations are queued or tracked over time, likely for longer-running actions such as diagnostics, indexing operations, or cluster tasks that the UI polls through the API.

8. The frontend lives under ui/ and is built separately from the Python backend. It is a component/container-based AngularJS-era app with services, filters, factories, and many feature modules. Webpack configs at the repo root bundle assets into elastichq/static/, which the backend serves.

9. UI architecture is feature-oriented around clusters and Elasticsearch objects. Containers and components cover cluster overview, nodes, indices, aliases, snapshots, diagnostics, query, REST API browsing, and settings. The UI uses dedicated services such as cluster-connection, cluster-indices, cluster-nodes, and hq to call the backend API.

10. Real-time and dashboard-style views are a major presentation boundary. Components such as line graphs, summary cards, node tables, and index metric panels consume backend data and render operational status for cluster health, docs, search load, JVM, filesystem, process, and shard state.

11. The templates/ and static/ directories on the Python side show that the backend also serves the SPA shell and compiled assets. elastichq/templates/index.html is the host page, while bundled CSS/JS in elastichq/static/ are the deployable frontend artifacts.

12. Testing is split along the same architectural lines. tests/es_versions/ exercises Elasticsearch-version-specific backend behavior, tests/combined/ covers integrated flows, and the various Docker Compose files under tests/ spin up versioned Elasticsearch environments. This is important because compatibility across ES 2.x through 7.x is a first-class architectural constraint.

13. Deployment is container-friendly and environment-driven. The repository includes a root Dockerfile, example Compose setups, and OpenShift manifests/proxy config, which implies the app is commonly deployed as a single web container that connects outward to user-provided Elasticsearch clusters rather than co-locating with Elasticsearch.

14. Documentation is generated with Sphinx and versioned under docs/, but it is not part of runtime behavior. The doc tree mirrors the backend module structure, which reinforces the separation between API layer, service layer, model layer, and frontend UI.

15. In diagram form, the key flow is: browser UI → ElasticHQ HTTP endpoints → service layer → Elasticsearch clusters, with a side path to local persistence for saved cluster metadata and a separate path for task/background bookkeeping. The backend is the central control plane; Elasticsearch is the data source and execution target.