---
module: fleet.modules
title: Modules
tab: Claude
order: 40
audience: dev
---

> **Internal · agent reference.** Terse. Confirmed against `hiveops-fleet` source 2026-07-01.

## Owner
- Service: **`hiveops-fleet`** (port **8097**, DB **`hiveiq_fleet`**). Serves SPA `fleet.bcos.cloud` + `/api/fleet`.
- Frontend view: `hiveops-fleet/frontend/src/components/FleetManagement/FleetModules.svelte`.

## Endpoints (confirmed)
| Method | Path | Auth (`@PreAuthorize`) | Behavior |
|--------|------|------------------------|----------|
| GET | `/api/fleet/modules/summary` | `hasAnyRole('USER','CUSTOMER','ADMIN','MSP_ADMIN','BCOS_ADMIN')` | Returns `List<ModuleSummaryDTO>` — **hardcoded `List.of()` (always empty)** |

Base path `@RequestMapping("/api/fleet")` in `FleetApiController`. Frontend base = `window.__APP_CONFIG__.apiUrl` (default `http://localhost:8097/api/fleet`).

## DTO
- `ModuleSummaryDTO { String moduleName; long runningCount; long disabledCount; long failedCount; long totalCount; }`
- Joined in UI by `moduleName === catalog.key`.

## Data facts
- Module catalog = **16 entries hardcoded in `FleetModules.svelte`** (`MODULE_CATALOG`), NOT from DB/API. Categories: `Data Collection`, `Monitoring`, `Fleet Management`, `Updates`.
- **No DB table** backs module status. **No Kafka topic** backs module status.
- Status badges never render today (summary is empty → `summaryFor()` returns null → `{#if summary}` skipped).

## Gotchas
- `/modules/summary` returning `[]` is **by design (stub)**, not a bug/outage. "No badges" = expected.
- Client methods `getModules()`→`GET /modules`, `getModulesByAtm(id)`→`GET /modules/atm/{id}` exist in `api.ts` but **have NO backend endpoint** in `FleetApiController` (would 404). Not called by this view. (unverified whether any other service implements them — none found in `hiveops-fleet`.)
- Module enable/disable is agent-config driven (`CONFIG_UPDATE` fleet task / config server), NOT this screen. This screen is read-only.
- `/api/fleet/**` = JWT plane (`JWT_SECRET`). Internal agent endpoints are `/api/internal/fleet/**` (`hasRole('INTERNAL')`, `X-Internal-Secret`) — unrelated to this feature.

## Do NOT
- Do NOT claim a `module_status` / `agent_module` table or a `hiveops.*.modules` Kafka topic exists — none do.
- Do NOT tell anyone module counts are "live" or reflect real ATM state — the endpoint returns empty.
- Do NOT route users to `/modules` or `/modules/atm/{id}` — no backend, will 404.
- Do NOT look in `hiveops-incident`/`devices`/`journal` for this screen's data — owner is `hiveops-fleet`, and the summary is a fleet stub.
- Do NOT edit the module list in the backend — the catalog lives in `FleetModules.svelte` (frontend), rebuild the fleet frontend to change it.
