# clustercockpit/cc-backend architecture

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

- Interactive diagram: https://gitdiagram.com/clustercockpit/cc-backend
- Repository: https://github.com/clustercockpit/cc-backend

## Overview

ClusterCockpit is an HPC job-performance monitoring web backend with REST and GraphQL APIs, a Svelte interface, job archives, and live metric integrations. The main user path is browser request → HTTP routing/API → job or metric query → database/metric backend → rendered dashboard or analysis view. Separate product branches cover batch-system event ingestion, authentication, fleet services, job archiving, and background retention. Relationships are limited to those shown in the excerpts, SOURCE INDEX references, or README; unsampled wiring is omitted.

Main entry points: [`internal/routerConfig/routes.go`](https://github.com/clustercockpit/cc-backend/blob/main/internal/routerConfig/routes.go) (Web routes), [`internal/graph/resolver.go`](https://github.com/clustercockpit/cc-backend/blob/main/internal/graph/resolver.go) (GraphQL API), [`internal/repository/jobQuery.go`](https://github.com/clustercockpit/cc-backend/blob/main/internal/repository/jobQuery.go) (Job query layer), [`cmd/cc-backend/server.go`](https://github.com/clustercockpit/cc-backend/blob/main/cmd/cc-backend/server.go) (HTTP server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_frontend["Svelte interface"]
  node_filter_components["Job filters<br/>[Filters.svelte]"]
  node_plot_components["Metric plots"]
  node_status_dashboard["Live dashboards"]
end

subgraph group_api["API and identity"]
  node_http_server["HTTP server<br/>[server.go]"]
  node_routes["Web routes<br/>[routes.go]"]
  node_auth["Authentication<br/>[auth.go]"]
  node_rest_api["REST API<br/>[rest.go]"]
  node_job_api["Job API<br/>[job.go]"]
  node_graph_api["GraphQL API<br/>[resolver.go]"]
end

subgraph group_data["Job and metric data"]
  node_job_queries["Job query layer<br/>[jobQuery.go]"]
  node_relational_db[("SQLite database<br/>[dbConnection.go]")]
  node_metric_dispatch["Metric dispatch<br/>[dataLoader.go]"]
  node_builtin_metrics[("Built-in metric store<br/>[query.go]")]
  node_external_metrics["External metric stores<br/>[cc-metric-store.go]"]
  node_job_archive[("Job archive<br/>[archive.go]")]
end

subgraph group_integrations["Cluster integrations"]
  node_nats_ingest["NATS event API<br/>[nats.go]"]
  node_fleet_services["Fleet services<br/>[services.go]"]
end

subgraph group_operations["Archiving and operations"]
  node_archive_worker["Archive worker<br/>[archiveWorker.go]"]
  node_background_tasks["Background tasks<br/>[taskManager.go]"]
  node_parquet_archive["Parquet archive<br/>[writer.go]"]
end

node_browser(("Browser user"))
node_cluster_system(("HPC batch system"))

node_browser -->|"sends requests"| node_http_server
node_http_server -->|"routes requests"| node_routes
node_http_server -->|"checks identity"| node_auth
node_routes -->|"routes jobs"| node_job_api
node_routes -->|"routes GraphQL"| node_graph_api
node_routes -->|"mounts REST"| node_rest_api
node_routes -->|"serves interface"| node_frontend
node_frontend -->|"queries data"| node_graph_api
node_filter_components -->|"filters views"| node_frontend
node_status_dashboard -->|"queries status"| node_graph_api
node_status_dashboard -->|"renders metrics"| node_plot_components
node_job_api -->|"queries jobs"| node_job_queries
node_job_queries -->|"reads records"| node_relational_db
node_graph_api -.->|"queries jobs"| node_job_queries
node_graph_api -.->|"loads metrics"| node_metric_dispatch
node_metric_dispatch -.->|"queries metrics"| node_builtin_metrics
node_metric_dispatch -.->|"queries external"| node_external_metrics
node_external_metrics -->|"uses archive data"| node_job_archive
node_cluster_system -.->|"publishes events"| node_nats_ingest
node_cluster_system -.->|"sends updates"| node_rest_api
node_nats_ingest -.->|"updates job state"| node_job_queries
node_fleet_services -->|"registers services"| node_relational_db
node_archive_worker -->|"archives completed jobs"| node_job_archive
node_archive_worker -->|"updates archive status"| node_job_queries
node_background_tasks -.->|"runs retention"| node_parquet_archive
node_background_tasks -->|"manages retention"| node_job_archive

click node_frontend "https://github.com/clustercockpit/cc-backend/tree/main/web/frontend/src"
click node_filter_components "https://github.com/clustercockpit/cc-backend/blob/main/web/frontend/src/generic/Filters.svelte"
click node_plot_components "https://github.com/clustercockpit/cc-backend/tree/main/web/frontend/src/generic/plots"
click node_status_dashboard "https://github.com/clustercockpit/cc-backend/blob/main/web/frontend/src/DashPublic.root.svelte"
click node_http_server "https://github.com/clustercockpit/cc-backend/blob/main/cmd/cc-backend/server.go"
click node_routes "https://github.com/clustercockpit/cc-backend/blob/main/internal/routerConfig/routes.go"
click node_auth "https://github.com/clustercockpit/cc-backend/blob/main/internal/auth/auth.go"
click node_rest_api "https://github.com/clustercockpit/cc-backend/blob/main/internal/api/rest.go"
click node_job_api "https://github.com/clustercockpit/cc-backend/blob/main/internal/api/job.go"
click node_graph_api "https://github.com/clustercockpit/cc-backend/blob/main/internal/graph/resolver.go"
click node_job_queries "https://github.com/clustercockpit/cc-backend/blob/main/internal/repository/jobQuery.go"
click node_relational_db "https://github.com/clustercockpit/cc-backend/blob/main/internal/repository/dbConnection.go"
click node_metric_dispatch "https://github.com/clustercockpit/cc-backend/blob/main/internal/metricdispatch/dataLoader.go"
click node_builtin_metrics "https://github.com/clustercockpit/cc-backend/blob/main/pkg/metricstore/query.go"
click node_external_metrics "https://github.com/clustercockpit/cc-backend/blob/main/internal/metricstoreclient/cc-metric-store.go"
click node_job_archive "https://github.com/clustercockpit/cc-backend/blob/main/pkg/archive/archive.go"
click node_nats_ingest "https://github.com/clustercockpit/cc-backend/blob/main/internal/api/nats.go"
click node_fleet_services "https://github.com/clustercockpit/cc-backend/blob/main/internal/fleet/services.go"
click node_archive_worker "https://github.com/clustercockpit/cc-backend/blob/main/internal/archiver/archiveWorker.go"
click node_background_tasks "https://github.com/clustercockpit/cc-backend/blob/main/internal/taskmanager/taskManager.go"
click node_parquet_archive "https://github.com/clustercockpit/cc-backend/blob/main/pkg/archive/parquet/writer.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_frontend,node_filter_components,node_plot_components,node_status_dashboard,node_browser toneBlue
class node_http_server,node_routes,node_auth,node_rest_api,node_job_api,node_graph_api toneAmber
class node_job_queries,node_relational_db,node_metric_dispatch,node_builtin_metrics,node_external_metrics,node_job_archive toneMint
class node_nats_ingest,node_fleet_services toneRose
class node_archive_worker,node_background_tasks,node_parquet_archive,node_cluster_system toneIndigo
```

## Components

### Web experience

- [Svelte interface](https://github.com/clustercockpit/cc-backend/tree/main/web/frontend/src): `web/frontend/src`
- [Job filters](https://github.com/clustercockpit/cc-backend/blob/main/web/frontend/src/generic/Filters.svelte): `web/frontend/src/generic/Filters.svelte`
- [Metric plots](https://github.com/clustercockpit/cc-backend/tree/main/web/frontend/src/generic/plots): `web/frontend/src/generic/plots`
- [Live dashboards](https://github.com/clustercockpit/cc-backend/blob/main/web/frontend/src/DashPublic.root.svelte): `web/frontend/src/DashPublic.root.svelte`

### API and identity

- [HTTP server](https://github.com/clustercockpit/cc-backend/blob/main/cmd/cc-backend/server.go): `cmd/cc-backend/server.go`
- [Web routes](https://github.com/clustercockpit/cc-backend/blob/main/internal/routerConfig/routes.go): `internal/routerConfig/routes.go`
- [Authentication](https://github.com/clustercockpit/cc-backend/blob/main/internal/auth/auth.go): `internal/auth/auth.go`
- [REST API](https://github.com/clustercockpit/cc-backend/blob/main/internal/api/rest.go): `internal/api/rest.go`
- [Job API](https://github.com/clustercockpit/cc-backend/blob/main/internal/api/job.go): `internal/api/job.go`
- [GraphQL API](https://github.com/clustercockpit/cc-backend/blob/main/internal/graph/resolver.go): `internal/graph/resolver.go`

### Job and metric data

- [Job query layer](https://github.com/clustercockpit/cc-backend/blob/main/internal/repository/jobQuery.go): `internal/repository/jobQuery.go`
- [SQLite database](https://github.com/clustercockpit/cc-backend/blob/main/internal/repository/dbConnection.go): `internal/repository/dbConnection.go`
- [Metric dispatch](https://github.com/clustercockpit/cc-backend/blob/main/internal/metricdispatch/dataLoader.go): `internal/metricdispatch/dataLoader.go`
- [Built-in metric store](https://github.com/clustercockpit/cc-backend/blob/main/pkg/metricstore/query.go): `pkg/metricstore/query.go`
- [External metric stores](https://github.com/clustercockpit/cc-backend/blob/main/internal/metricstoreclient/cc-metric-store.go): `internal/metricstoreclient/cc-metric-store.go`
- [Job archive](https://github.com/clustercockpit/cc-backend/blob/main/pkg/archive/archive.go): `pkg/archive/archive.go`

### Cluster integrations

- [NATS event API](https://github.com/clustercockpit/cc-backend/blob/main/internal/api/nats.go): `internal/api/nats.go`
- [Fleet services](https://github.com/clustercockpit/cc-backend/blob/main/internal/fleet/services.go): `internal/fleet/services.go`

### Archiving and operations

- [Archive worker](https://github.com/clustercockpit/cc-backend/blob/main/internal/archiver/archiveWorker.go): `internal/archiver/archiveWorker.go`
- [Background tasks](https://github.com/clustercockpit/cc-backend/blob/main/internal/taskmanager/taskManager.go): `internal/taskmanager/taskManager.go`
- [Parquet archive](https://github.com/clustercockpit/cc-backend/blob/main/pkg/archive/parquet/writer.go): `pkg/archive/parquet/writer.go`

### Other components

- **Browser user**
- **HPC batch system**

## Connections

- Browser user → HTTP server: sends requests
- HTTP server → Web routes: routes requests (evidence: `cmd/cc-backend/server.go`)
- HTTP server → Authentication: checks identity (evidence: `cmd/cc-backend/server.go`)
- Web routes → Job API: routes jobs (evidence: `internal/routerConfig/routes.go`)
- Web routes → GraphQL API: routes GraphQL (evidence: `internal/routerConfig/routes.go`)
- Web routes → REST API: mounts REST
- Web routes → Svelte interface: serves interface (evidence: `internal/routerConfig/routes.go`)
- Svelte interface → GraphQL API: queries data (evidence: `web/frontend/src/DashPublic.root.svelte`)
- Job filters → Svelte interface: filters views (evidence: `web/frontend/src/generic/Filters.svelte`)
- Live dashboards → GraphQL API: queries status (evidence: `web/frontend/src/DashPublic.root.svelte`)
- Live dashboards → Metric plots: renders metrics (evidence: `web/frontend/src/DashPublic.root.svelte`)
- Job API → Job query layer: queries jobs (evidence: `internal/api/job.go`)
- Job query layer → SQLite database: reads records (evidence: `internal/repository/jobQuery.go`)
- GraphQL API → Job query layer: queries jobs
- GraphQL API → Metric dispatch: loads metrics
- Metric dispatch → Built-in metric store: queries metrics
- Metric dispatch → External metric stores: queries external
- External metric stores → Job archive: uses archive data (evidence: `internal/metricstoreclient/cc-metric-store.go`)
- HPC batch system → NATS event API: publishes events
- HPC batch system → REST API: sends updates
- NATS event API → Job query layer: updates job state
- Fleet services → SQLite database: registers services (evidence: `internal/fleet/services.go`)
- Archive worker → Job archive: archives completed jobs (evidence: `internal/archiver/archiveWorker.go`)
- Archive worker → Job query layer: updates archive status (evidence: `internal/archiver/archiveWorker.go`)
- Background tasks → Parquet archive: runs retention
- Background tasks → Job archive: manages retention
