# GuruConnect — Architecture Decisions

Records significant architectural decisions for the GuruConnect product. Each entry: context,
decision, options considered, rationale, consequences.

---

## ADR-001: GuruConnect is a Standalone Product; Integrate with GuruRMM via a Versioned Contract

**Date:** 2026-05-29
**Status:** Decided
**Deciders:** Mike Swanson

### Context

GuruConnect is a remote-support product that must work fully on its own, with its own repository
(`azcomputerguru/guru-connect`), build pipeline, and release cadence. GuruRMM wants to offer native
integrated remote control by driving GuruConnect.

### Decision

GuruConnect stays an independent product. It exposes a **versioned integration contract**
(`/api/integration/v1/`, capability discovery, embedded-viewer protocol) that GuruRMM consumes as a
broker. The two products do not share build pipelines or release in lockstep. GuruConnect owns the
contract; GuruRMM does no active development on GuruConnect.

### Rationale

- Preserves GuruConnect as a sellable standalone product.
- Avoids coupling two independently-evolving codebases; integration changes go through the contract.
- Mirrors the GuruRMM-side decision (GuruRMM ADR-008).

### Consequences

- The integration surface is semver'd; breaking changes require a major bump.
- See `docs/specs/native-remote-control/` for the contract spec.

---

## ADR-002: Release Engineering — Gitea Actions Pipeline with Azure Trusted Signing

**Date:** 2026-05-29
**Status:** Decided
**Deciders:** Mike Swanson

### Context

GuruConnect needs operational parity with GuruRMM: signed Windows binaries, automatic versioning,
changelogs, and tracking. GuruRMM achieves this with a Gitea **webhook → shell-script** pipeline on
shared build hosts (Saturn + Pluto) and signs via Azure Trusted Signing (`jsign`) using credentials
in `/etc/gururmm-signing.env`.

### Decision

GuruConnect implements its release engineering **entirely in Gitea Actions** (not the webhook/script
model), and **reuses GuruRMM's existing Azure Trusted Signing certificate profile** (same account +
service principal) to sign the Windows agent `.exe`.

### Options Considered

- **A — Gitea Actions, reuse RMM cert profile (chosen):** self-contained workflows; `jsign` runs on
  the `ubuntu-latest` runner; no Pluto/webhook dependency. GC ships a single `.exe` (no WiX/MSI), so
  no Windows runner is needed.
- **B — Mirror RMM's webhook + shell scripts:** maximal parity but adds Pluto/webhook coupling and a
  build host to maintain.
- **C — Separate Azure Trusted Signing account for GC:** cleaner attribution, more Azure setup.

### Rationale

- `jsign` is cross-platform (Java) and signs PE binaries on Linux — no Windows runner required.
- Reusing RMM's cert profile means zero new Azure provisioning; GC binaries are signed by the same
  ACG identity.
- Actions are self-contained and versioned with the repo, simpler than maintaining build-host scripts.

### Consequences

- The Azure Trusted Signing service-principal secrets must be added to the `guru-connect` repo's
  Gitea Actions secrets (values come from `/etc/gururmm-signing.env` / the SOPS vault). See SPEC-001.
- Windows binaries will be attributed to GuruRMM's cert profile until/unless a GuruConnect-specific
  profile is provisioned (a future, low-effort change).
- Implementation: `docs/specs/SPEC-001-operational-tooling-parity.md`.