docs: rewrite CLAUDE.md for delta-v microservice architecture

[pbrane]

Why

The repo's CLAUDE.md was inherited largely intact from upstream OpenNMS Horizon and described an architecture delta-v no longer has — Apache Karaf/OSGi, JAXB config, ActiveMQ, the bin/opennms monolith, CircleCI, JIRA conventions, and module trees (features/, container/, ui/, dependencies/, opennms-*) that do not exist in this slim reactor. That makes it actively misleading guidance for both humans and Claude Code.

This PR rewrites it to describe delta-v as it actually is, and promotes the project's load-bearing invariants (previously only living in a personal Claude memory store) into the checked-in file so every contributor shares them.

What changed

• New "Delta-V Architecture & Conventions (CRITICAL)" section distilling the invariants:
  • No Karaf/OSGi — Spring Boot 4 daemon microservices (core/daemon-boot-*)
  • No events table / Eventd / in-JVM EventBus — events flow through Kafka
  • Minion-mandatory I/O; gRPC only for the minion-gateway↔Minion channel
  • RPC timeouts must never create outages or fault events
  • No ActiveMQ / Newts / legacy webapp; Prometheus/VictoriaMetrics + ClickHouse
  • DB identity is deltav (values only — org.opennms.* packages and env/property KEYS keep their names)
  • org.deltav.* packages; Jackson XmlMapper not JAXB; Conventional Commits + GitHub issues not JIRA; branch + PR; horizon consumed as pre-built JARs
• Corrected Module Organization (~34-module reactor: core/, deploy/, tools/, components/, docs/), Runtime Architecture, the tech-stack table, Testing, Branching Model, Key Conventions, and CI/CD (GitHub Actions, not CircleCI).
• The pre-existing Git Remote rule (never PR against OpenNMS/*) is untouched.

Docs-only; no code or build changes.

https://claude.ai/code/session_01XgRQL9QZcghyiLFXM9ZUnW

[indigo423]

Frontend topic might be a bit misleading

[indigo423]

All the frontend stack is gone

[indigo423]

Review suggestions — CLAUDE.md rewrite (non-blocking, your call)

Net assessment: strong, net-positive rewrite. It removes genuinely misleading upstream-Horizon guidance (Karaf, JAXB, ActiveMQ, bin/opennms, CircleCI) and promotes the real delta-v invariants into the checked-in file — exactly what Anthropic's CLAUDE.md best-practices ask for.

I verified the load-bearing claims against the tree and most check out: Spring Boot 4.0.3 ✓, PostgreSQL 16 ✓, db identity deltav with OPENNMS_DBINIT_*/SPRING_DATASOURCE_* keys retained ✓, 14 daemon-boot-* modules ✓, the four .github/workflows/ files ✓, no ui/ module ✓, MODULE=:org.opennms.core.daemon-boot-pollerd matches the real artifactId ✓, JAR consumption via deltav.horizon.version ✓. I also confirmed Hibernate 7: core/daemon-boot-pollerd resolves org.hibernate.orm:hibernate-core:7.2.4.Final — the org.hibernate:hibernate-core:3.6.11 pin in pom.xml is the legacy coordinate (different groupId) and does not downgrade the daemons. So that row is accurate as written.

Four things to consider, ranked. Take or leave any of them.

1. (Most impactful) The 36.0.0-SNAPSHOT version claim looks wrong — line ~57

"The Maven reactor inherits Horizon's 36.0.0-SNAPSHOT version; the deployable Docker images are versioned on delta-v's own 1.x line."

Root pom.xml declares org.deltav:delta-v-parent at <version>1.3.0</version>, and grep '36.0.0' pom.xml returns nothing. The reactor is on the same 1.x line as the images (1.3.0); Horizon comes in only as a BOM import at deltav.horizon.version=1.0.19. Suggested rewording:

The reactor and Docker images share delta-v's own 1.x version line (currently 1.3.0); upstream Horizon is consumed only as pre-built JARs at deltav.horizon.version (currently 1.0.19).

2. Dangling "legacy guidance further down" reference — lines ~21-22

"Significant parts of the 'legacy' guidance further down (Karaf, JAXB config, ActiveMQ/JMS, the bin/opennms monolith, CircleCI, JIRA) describe upstream Horizon and do not apply..."

This same PR deletes all of that legacy guidance. After the rewrite, "Karaf" survives only inside the new "no Karaf" assertions, CircleCI is gone, bin/opennms appears only in a "not used" note — so the sentence points readers (and Claude) at sections that no longer exist. Suggest dropping the "further down" clause; the section stands on its own as a positive statement of what delta-v is.

3. "every delta-v module" list is incomplete; "~34" is off by one — lines ~118, ~122

The reactor has exactly 33 modules (grep -c '<module>' pom.xml), all under core/. The list under "core/ — every delta-v module:" omits three: poller-service-catalog, poller-timeseries-common, and prometheus-writer (the last is named only as a runtime aux image, not in the module list). Either add the three, or soften "every delta-v module" → "the delta-v modules include" and "~34" → "33".

4. (Polish) Duplication vs. the best-practices "keep it concise" guidance — multiple lines

"No Karaf/OSGi" is restated in the invariants, the Runtime blockquote, the tech-stack row, Key Conventions, and CI/CD; "Jackson XmlMapper, not JAXB" appears three times. Optional: state each invariant once in the CRITICAL section and reference it later, to keep the file tight and prevent the copies from drifting apart over time.

---

#1 and #2 are the two I'd prioritize (factual error + self-contradiction within the PR); #3 and #4 are easy polish in the same pass. All entirely your call on if/how to apply.

_{🤖 Generated with Claude Code}

[pbrane]

Thanks for the careful review, @indigo423 — you were right on all four, and I re-verified each against the tree before fixing. Pushed in the follow-up commit:

1. Frontend (your requested change) — you're correct that the stack is gone, not relocated. Confirmed: no ui/ dir and zero vite/vue/pinia/pnpm references anywhere in the repo. Removed the tech-stack row and rewrote the section to say delta-v has no frontend; the operator surface is Grafana + per-daemon Spring Boot Actuator. My earlier "SPA lives in delta-v-horizon" framing was the misleading part — dropped.
2. 36.0.0-SNAPSHOT — removed. grep '36.0.0' pom.xml returns nothing; parent is org.deltav:delta-v-parent 1.3.0. Reworded to: reactor + images share the 1.x line (1.3.0), horizon consumed as JARs at deltav.horizon.version (1.0.19). (This was exactly the "inherited fiction" this PR set out to kill, reproduced one level down — good catch.)
3. Module count — confirmed exactly 33 (grep -c '<module>' pom.xml). Added the three omitted modules (poller-service-catalog, poller-timeseries-common, prometheus-writer) and softened "every delta-v module" → "the delta-v modules … representative, not exhaustive".
4. Dangling "further down" — dropped; this PR deletes those sections so the pointer was stale.

On your suggestion #4 (duplication): I deliberately kept the intentional restatements. In a CLAUDE.md that's read in fragments, a self-contained invariant in each section is more robust than a single definition + cross-references — and the risk of copies drifting is low for hard invariants like "no Karaf". Happy to tighten if you feel strongly.

[indigo423]

Go for it!