---
module: fleet.modules
title: Modules
tab: Architect
order: 30
audience: dev
---

> **Internal · architecture.** Written 2026-07-01 from `hiveops-fleet` source. Verify against code before relying on specifics.

## Shape of the feature
The **Agent Modules** screen is intentionally thin. It is a **client-owned catalog** plus a **single fleet-wide summary endpoint**. There is no dedicated module-status table, no Kafka topic, and no executor→record-store pipeline behind this specific screen today. Cross-link [platform.service-ownership].

### Two data sources, one of them static
1. **Module catalog (static, frontend):** `MODULE_CATALOG` in `hiveops-fleet/frontend/src/components/FleetManagement/FleetModules.svelte` — a hardcoded array of 16 `{ key, displayName, description, category }` entries across four categories: `Data Collection`, `Monitoring`, `Fleet Management`, `Updates`. The `key`s (e.g. `journal-events`, `command-center`, `auto-update`) mirror the agent's module identifiers. No backend call produces this list.
2. **Status summary (dynamic, backend):** `GET /api/fleet/modules/summary` on `hiveops-fleet`, deserialized to `ModuleSummary[]` in the frontend store `moduleSummary` (`loadModuleSummary()` in `stores.ts`). The component joins the two by matching `ModuleSummary.moduleName === catalog.key`.

## Service ownership
- **Owner:** `hiveops-fleet` (port 8097, DB `hiveiq_fleet`). It serves both the SPA (`fleet.bcos.cloud`) and the `/api/fleet` REST surface.
- No other service participates in **this** feature. (Broadly, fleet syncs a `device_summary` mirror from `hiveops.device.events` and publishes task events on `hiveops.fleet.task.events` — see [technical.fleet] — but neither pipeline feeds the Modules screen.)

## Data flow (current)
```
FleetModules.svelte (onMount)
  → loadModuleSummary()            [stores.ts]
    → fleetAPI.getModuleSummary()  [api.ts]  GET {apiUrl}/modules/summary
      → FleetApiController.getModuleSummary()  [hiveops-fleet]
        → return List.of();        ← STUB: always empty
  → moduleSummary store = []
  → component renders 16 static cards; no badges (summaryFor() always null)
```

### Endpoint detail (confirmed)
| Method + Path | Controller | Auth | Returns |
|---------------|-----------|------|---------|
| `GET /api/fleet/modules/summary` | `FleetApiController.getModuleSummary()` | `@PreAuthorize hasAnyRole('USER','CUSTOMER','ADMIN','MSP_ADMIN','BCOS_ADMIN')` | `List<ModuleSummaryDTO>` — currently `List.of()` (empty) |

`ModuleSummaryDTO` fields: `moduleName` (String), `runningCount`, `disabledCount`, `failedCount`, `totalCount` (all `long`). Frontend `ModuleSummary` interface mirrors these.

## DB tables read/written
- **None for this feature.** The summary endpoint returns a static empty list; it does not query any table. The `hiveiq_fleet` schema (V1__init_fleet.sql: `fleet_tasks`, `fleet_task_history`, `fleet_artifacts`, `patch_windows`, `atm_captures`, `device_summary`) has **no module-status table**. Cross-link [platform.data-architecture].

## Kafka
- **None for this feature.** No producer or consumer touches module status. (Fleet's Kafka wiring — `FleetTaskEventPublisher` → `hiveops.fleet.task.events`, and `DeviceEventConsumer` ← `hiveops.device.events` — is unrelated to the Modules screen.) Cross-link [platform.kafka].

## If/when this gets wired for real
The DTO already models per-module aggregate counts (running/disabled/failed/total), which implies the intended source is a per-ATM module-status feed aggregated by `moduleName`. That feed does not exist in fleet today. A future implementation would need agents to report module state (via agent-proxy internal endpoints, the pattern used elsewhere: agent → `X-Internal-Secret` `/api/internal/fleet/**`), land it in a new fleet table, and aggregate in `getModuleSummary()`. Until then, treat the screen as documentation-only.

## Cross-links
- [platform.data-architecture]
- [platform.kafka]
- [platform.service-ownership]
- [technical.fleet] — fleet task orchestration, artifact delivery, the real Kafka/table surface of `hiveops-fleet`
