# HiveOps Agent — Project Memory

## Key Architecture

- **Multi-module Maven project** (Java 21, fat JAR via maven-shade-plugin)
- **Main class:** `com.hiveops.AgentApplication`
- **Fat JAR output:** `hiveops-app/target/hiveops-{version}-jar-with-dependencies.jar`
- **Current version:** `3.0.2-SNAPSHOT` (next dev after `3.0.2` release)
- **Git remote:** `http://192.168.200.102/hiveops/hiveops-agent.git` (Gitea)

## Service Endpoints (Production)

- `server.endpoint` → `https://api.bcos.cloud/mgmt` — fleet management, file uploads, command polling
- `incident.endpoint` → `https://api.bcos.cloud/incident` — heartbeat, journal events, connection status

## Known Bug Fixed (2026-02-27)

**Heartbeat was going to the wrong service.**

`HttpHeartbeat` (in `AgentApplication.init()`) was created with `settings` (mgmt endpoint), but the
handler that updates `lastHeartbeat` in the incident DB is `AtmAgentController.heartbeat()` in
hiveops-incident at `{incident.endpoint}/atm/heartbeat`.

Fix: `AgentApplication.java:472-474` — now loads `incidentSettings` from `"incident"` prefix and
passes those to `HttpHeartbeat`. Committed as `5cb5d65`.

## Heartbeat Details

- **Sent from:** `HttpHeartbeat` (`hiveops-core/.../http/HttpHeartbeat.java`)
- **URL:** `{incident.endpoint}/atm/heartbeat` (PUT)
- **Payload:** `{ country, name, logtype, heartbeat (unix ms) }`
- **Interval:** `heartbeat.interval` property (default 5 min)
- **Received by:** `AtmAgentController.heartbeat()` in hiveops-incident
- **Connection status thresholds:** CONNECTED ≤15 min, DISCONNECTED >15 min, NEVER_CONNECTED = null

## Distribution Build System

**Script:** `deployment/build-dist.sh`

```bash
# Standard full release (all platforms)
deployment/build-dist.sh --release --platform all

# Patch release (JAR only, no config overwrite)
deployment/build-dist.sh --release --patch --platform all

# Scotia variant (includes Scotiabank ext configs)
deployment/build-dist.sh --release --scotia --platform all
```

**Output:** `deployment/dist/hiveops-agent-{version}-{variant}-{platform}.{tar.gz|zip}`

**Variants:** `standard`, `patch`, `scotia`

## Patch vs Full Release

| | Full | Patch |
|--|--|--|
| hiveops-agent.jar | ✓ | ✓ |
| hiveops.properties | ✓ | ✗ |
| ext/*.properties | ✓ | ✗ |
| log4j2.xml | ✓ | ✗ |
| install script | install.sh / install.cmd | patch.sh / patch.cmd |

Patch installer: stops service → backs up JAR (timestamped `.bak`) → installs new JAR → restarts.

## Version Management Workflow

```bash
# 1. Bump to new SNAPSHOT (e.g. 3.0.1 → 3.0.2)
mvn versions:set -DnewVersion=3.0.2-SNAPSHOT -DgenerateBackupPoms=false

# 2. Build release (--release strips SNAPSHOT, builds 3.0.2, reverts POMs to 3.0.2-SNAPSHOT)
deployment/build-dist.sh --release --platform all

# 3. Commit + tag
git add pom.xml */pom.xml
git commit -m "Bump version to 3.0.2-SNAPSHOT"
git tag v3.0.2
git push && git push origin v3.0.2
```

## Key File Locations

| File | Path |
|------|------|
| Main config (Linux default) | `hiveops-app/src/main/resources/hiveops.properties` |
| Main config (Windows override) | `deployment/windows/hiveops.properties` |
| Windows ext configs | `deployment/windows/ext/` |
| Linux ext configs | `hiveops-app/src/main/resources/ext/` |
| Windows scripts | `deployment/windows/scripts/` (incl. startupproj.bat, stopagent.bat) |
| Linux scripts | `hiveops-app/src/main/resources/scripts/` |
| Patch installer (Linux) | `deployment/linux/patch.sh` |
| Patch installer (Windows) | `deployment/windows/patch.cmd` |
| Build script | `deployment/build-dist.sh` |
| Linux installer | `deployment/linux/install.sh` |
| Windows installer | `deployment/windows/install.cmd` |

## Windows Install Paths

- Install dir: `C:\hiveops-agent\`
- Start: `C:\hiveops-agent\startupproj.bat`
- Stop: `C:\hiveops-agent\stopagent.bat` (kills javaw.exe with hiveops in cmdline)

## Linux Install Paths

- Install dir: `/opt/hiveops/`
- Config dir: `/etc/hiveops/`
- Log dir: `/var/log/hiveops/`
- Service: `hiveops-agent` (systemd)