feat(classification): unify host classification into one explainable panel

[NotYuSheng]

What & why

After #556, clicking a device badge in the Conversation Detail view opened a legacy single-deviceType popup (DeviceClassificationPopup) — a thinner, different modal than the axis-based explainable classification the network graph shows. This unifies every host-inspection surface onto one shared HostIdentitySection so users see how a classification was derived and can correct/append to it everywhere.

Changes

Backend

• New GET /files/{fileId}/hosts/{ip}/identity → HostIdentityEvidenceDto: the adjudicated verdict (label/basis/confidence/contested/candidates) plus the measured evidence axes (hardware, service + nDPI apps, behaviour), composed in HostIdentityEvidenceService from existing SPI lookups — no new queries.
• Behaviour axis carries direction-independent fan-out (conversationCount/peerCount), so a high-peer router still shows real evidence on captures where nDPI never measured flow direction (was "Nothing observed").
• Geolocation (country/flag, ASN, org, geo-source) added to the DTO via GeoOrgLookup (offline-capable) — external hosts only.

Frontend

• Extracted the graph-only Identity + 3-axes + adjudication block into shared HostIdentitySection; NodeDetails and EntityDetailModal both render it. Removes HostClassificationSection/useHostClassification and the legacy DeviceClassificationPopup.
• New Geolocation block in the shared panel (restored from the old conversation modal, now unreachable once host detail routed through NodeDetails).
• Conversation redesign: Source ↔ Destination flow header; each host card shows its identity chip (confidence pill top-left) and opens the full EntityDetailModal. Metadata regrouped into a security strip + collapsible Timing/Geo/HTTP/TLS groups, all open by default.
• Removed the dead buildDeviceSignals block from deviceType.ts.

Contract

• OpenAPI baseline regenerated for the new endpoint + DTO fields.

Verification

• Backend endpoint returns real data end-to-end; geo verified with a seeded external record.
• Frontend type-check clean; all 145 unit tests pass (2 new fan-out tests).
• Docker stack builds and runs; Playwright confirms the flow header + host click opening the rich modal in light and dark themes.

Notes

• The "Why → LABEL (0)" empty reasons on the existing fixtures is stale data — those files were analyzed before scores/reasons were persisted; re-analyzing fills them in. Not a code change.
• The fixture captures are all-internal traffic, so the Geolocation block is correctly empty on them (external hosts show it).

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added detailed host identity evidence for individual IP addresses, including verdicts, confidence, device and service details, behavior metrics, and geolocation.
  • Redesigned host details to show explainable identity evidence, conflicts, candidate classifications, and data provenance.
  • Replaced the device classification popup with a shared host details experience across conversation and network views.
  • Improved conversation details with grouped metadata, host identity cards, confidence indicators, and security signals.

• Bug Fixes

  • Behavior evidence now remains available when connection direction data is unavailable by using conversation and peer metrics.

[gemini-code-assist]

Caution

The consumer version of Gemini Code Assist on GitHub has been sunset. All code review activity has officially ceased.

[coderabbitai]

Warning

Review limit reached

@NotYuSheng, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 45 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 2a8a29aa-d8ff-46fd-8de9-098af2639d9f

📥 Commits

Reviewing files that changed from the base of the PR and between 024dc17 and 281e311.

📒 Files selected for processing (6)

• backend/src/main/java/com/tracepcap/insights/service/HostIdentityEvidenceService.java
• frontend/src/components/common/EntityDetailModal/EntityDetailModal.tsx
• frontend/src/components/common/HostIdentitySection/HostIdentitySection.tsx
• frontend/src/components/conversation/ConversationDetail/ConversationDetail.css
• frontend/src/components/conversation/ConversationDetail/ConversationDetail.tsx
• frontend/src/components/network/NodeDetails/NodeDetails.tsx

📝 Walkthrough

Walkthrough

The change adds a host identity evidence API and shared frontend identity section, replaces legacy classification displays, redesigns conversation metadata and host navigation, centralizes node identity rendering, and adds behaviour-axis fan-out evidence fallback logic.

Changes

Host identity evidence redesign

Layer / File(s)	Summary
Evidence API and data contract backend/src/main/java/com/tracepcap/insights/..., frontend/src/types/..., frontend/src/services/api/endpoints.ts, frontend/src/features/conversation/services/..., openapi/baseline.json	Adds the evidence DTO and service, exposes GET /files/{fileId}/hosts/{ip}/identity, aggregates identity, conversation, and geolocation facts, and publishes matching frontend and OpenAPI contracts.
Shared identity evidence section frontend/src/components/common/HostIdentitySection/*, frontend/src/components/common/EntityDetailModal/..., frontend/src/utils/deviceType.ts	Replaces legacy classification rendering with shared verdict, evidence-axis, conflict, geolocation, loading, and adjudication UI.
Conversation identity flow and metadata frontend/src/components/conversation/ConversationDetail/*	Adds identity-backed host flow cards, IP detail navigation, grouped metadata, security signals, responsive layout, and themed styling.
Network node identity integration frontend/src/components/network/NodeDetails/NodeDetails.tsx	Removes local adjudication state and evidence panels and delegates identity rendering to HostIdentitySection.
Behaviour evidence fallback frontend/src/features/network/classificationAxes.ts, frontend/src/features/network/types/index.ts, frontend/src/features/network/__tests__/classificationAxes.test.ts	Adds direction-independent conversation and peer metrics as a fallback when initiator direction is unavailable, with precedence tests for measured direction data.

Estimated code review effort: 4 (Complex) | ~60 minutes

Sequence Diagram(s)

sequenceDiagram
  participant ConversationDetail
  participant EntityDetailModal
  participant HostIdentitySection
  participant conversationService
  participant IdentityEvidenceAPI
  ConversationDetail->>EntityDetailModal: Open IP details
  EntityDetailModal->>HostIdentitySection: Render fileId and ip
  HostIdentitySection->>conversationService: getHostIdentityEvidence(fileId, ip)
  conversationService->>IdentityEvidenceAPI: GET host identity evidence
  IdentityEvidenceAPI-->>conversationService: HostIdentityEvidence
  conversationService-->>HostIdentitySection: Evidence payload
  HostIdentitySection-->>EntityDetailModal: Render verdict and evidence axes

Loading

Possibly related PRs

• NotYuSheng/TracePcap#424: Earlier classification-based modal plumbing in the same entity detail path.
• NotYuSheng/TracePcap#441: Prior changes to the host classification section replaced by this identity section.
• NotYuSheng/TracePcap#537: Related HostIdentity adjudication and evidence-model refactoring.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 60.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: consolidating host classification into a shared explainable panel.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 10

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

frontend/src/components/network/NodeDetails/NodeDetails.tsx (1)

52-52: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Stale comment.

This comment describes the evidence explainer/axis-expansion state that moved into HostIdentitySection; it now sits above the tab state. Remove it.

🧹 Drop the orphaned comment

-  // Evidence header explainer modal, and which axis fact row is expanded to its derivation.
   const [activeTab, setActiveTab] = useState<Tab>('details');

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@frontend/src/components/network/NodeDetails/NodeDetails.tsx` at line 52,
Remove the stale evidence explainer/axis-expansion comment near the tab state in
NodeDetails; that state now belongs to HostIdentitySection, so leave the
surrounding tab-state code unchanged.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In
`@backend/src/main/java/com/tracepcap/insights/service/HostIdentityEvidenceService.java`:
- Around line 53-60: The lazy adjudication flow in HostIdentityEvidenceService
must handle concurrent adjudication safely. Update the logic around
hostIdentityRepository.findByFileId and hostIdentityService.adjudicateFile to
catch a losing DataIntegrityViolationException, then re-read the identities and
continue the existing IP filtering path; reuse the established getHostIdentities
recovery behavior or centralize that handling in the adjudication service.

In `@frontend/src/components/common/EntityDetailModal/EntityDetailModal.tsx`:
- Around line 144-146: Update the IP branch in EntityDetailModal so
HostIdentitySection renders only when fileId is non-empty, matching the existing
fileId guards used by the roles/statistics sections while preserving the
entityType === 'IP' condition.

In `@frontend/src/components/common/HostIdentitySection/HostIdentitySection.tsx`:
- Around line 336-338: Update the explanatory paragraph in HostIdentitySection
so its opening reference says “the evidence axes in this panel” instead of “the
evidence axes below,” accurately referring to the modal’s content while
preserving the rest of the copy.
- Line 290: Add aria-hidden="true" to the decorative chevron icon in
HostIdentitySection and the warning glyph at the corresponding warning-icon
location, matching the existing treatment of the info icon. Preserve their
current classes and rendering behavior.
- Around line 123-124: Introduce or reuse a shared deviceTypeFromLabel() helper
in `@/utils/deviceType`, then map the adjudicated primaryLabel through it instead
of casting: update HostIdentitySection.tsx lines 123-124 before assigning
nodeData.deviceType, and ConversationDetail.tsx lines 171-175 before unioning
identity?.primaryLabel with cls?.deviceType. Ensure axisFacts,
detectAxisConflict, deviceTypeColor, and deviceTypeIcon receive actual
DeviceType codes; no direct change is needed elsewhere.

In
`@frontend/src/components/conversation/ConversationDetail/ConversationDetail.css`:
- Around line 67-77: Merge the later .cd-host-role declaration containing
margin-left: auto with the existing .cd-host-role block, keeping all
declarations in one rule. Remove the duplicate selector and preserve the
resulting styles, including the intended margin-left behavior alongside
align-self.
- Line 161: Remove the duplicate `@media` (max-width: 700px) rule for .cd-groups
in ConversationDetail.css, keeping a single rule with grid-template-columns:
1fr.
- Around line 119-124: Update the .cd-host-open visibility rules alongside
.cd-host:hover so the hint also becomes visible when the associated .cd-host
receives :focus-visible. Preserve the existing hover behavior and styling.

In
`@frontend/src/components/conversation/ConversationDetail/ConversationDetail.tsx`:
- Around line 374-416: The HostFlowCard instances in the flow header should only
be interactive when ConversationDetailProps.fileId is defined. Update the
onOpen/interactive behavior for both source and destination cards, and suppress
the “Open full host details →” affordance when fileId is absent, while
preserving the existing modal behavior when fileId is available.
- Around line 299-316: Update the identity-loading effect around
getHostIdentities and the EntityDetailModal close flow so identityMap is
refreshed whenever the host modal closes after an override, not only when fileId
changes. Reuse the existing fetch/stale-response protection, and scope the
request to the two endpoint IPs if the service API supports it.

---

Outside diff comments:
In `@frontend/src/components/network/NodeDetails/NodeDetails.tsx`:
- Line 52: Remove the stale evidence explainer/axis-expansion comment near the
tab state in NodeDetails; that state now belongs to HostIdentitySection, so
leave the surrounding tab-state code unchanged.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 11039a35-4e8d-4900-b40f-8526bbd9226c

📥 Commits

Reviewing files that changed from the base of the PR and between 41a819e and 024dc17.

📒 Files selected for processing (20)

• backend/src/main/java/com/tracepcap/insights/controller/HostIdentitiesController.java
• backend/src/main/java/com/tracepcap/insights/dto/HostIdentityEvidenceDto.java
• backend/src/main/java/com/tracepcap/insights/service/HostIdentityEvidenceService.java
• frontend/src/components/common/DeviceClassificationPopup/DeviceClassificationPopup.tsx
• frontend/src/components/common/EntityDetailModal/EntityDetailModal.tsx
• frontend/src/components/common/EntityDetailModal/hooks/useHostClassification.ts
• frontend/src/components/common/EntityDetailModal/sections/HostClassificationSection.tsx
• frontend/src/components/common/HostIdentitySection/HostIdentitySection.tsx
• frontend/src/components/common/HostIdentitySection/index.ts
• frontend/src/components/conversation/ConversationDetail/ConversationDetail.css
• frontend/src/components/conversation/ConversationDetail/ConversationDetail.tsx
• frontend/src/components/network/NodeDetails/NodeDetails.tsx
• frontend/src/features/conversation/services/conversationService.ts
• frontend/src/features/network/__tests__/classificationAxes.test.ts
• frontend/src/features/network/classificationAxes.ts
• frontend/src/features/network/types/index.ts
• frontend/src/services/api/endpoints.ts
• frontend/src/types/common.types.ts
• frontend/src/utils/deviceType.ts
• openapi/baseline.json

💤 Files with no reviewable changes (4)

• frontend/src/components/common/EntityDetailModal/hooks/useHostClassification.ts
• frontend/src/components/common/DeviceClassificationPopup/DeviceClassificationPopup.tsx
• frontend/src/components/common/EntityDetailModal/sections/HostClassificationSection.tsx
• frontend/src/utils/deviceType.ts

[coderabbitai]

🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Adjudicated primaryLabel is a display string but is cast to DeviceType in two places. The verdict vocabulary (DEVICE_TYPES.map(deviceTypeLabel)) differs from the DeviceType codes consumed by the axis helpers and the icon/color utilities, so both casts silently produce unmatched values rather than a type error.

• frontend/src/components/common/HostIdentitySection/HostIdentitySection.tsx#L123-L124: map the label back to a DeviceType before assigning nodeData.deviceType, so axisFacts and detectAxisConflict see a real code.
• frontend/src/components/conversation/ConversationDetail/ConversationDetail.tsx#L171-L175: apply the same mapping to identity?.primaryLabel before unioning it with cls?.deviceType for deviceTypeColor/deviceTypeIcon.

Cleanest fix is a shared deviceTypeFromLabel() helper in @/utils/deviceType (or have the evidence DTO carry the code alongside the label).

📍 Affects 2 files

• frontend/src/components/common/HostIdentitySection/HostIdentitySection.tsx#L123-L124 (this comment)
• frontend/src/components/conversation/ConversationDetail/ConversationDetail.tsx#L171-L175

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@frontend/src/components/common/HostIdentitySection/HostIdentitySection.tsx`
around lines 123 - 124, Introduce or reuse a shared deviceTypeFromLabel() helper
in `@/utils/deviceType`, then map the adjudicated primaryLabel through it instead
of casting: update HostIdentitySection.tsx lines 123-124 before assigning
nodeData.deviceType, and ConversationDetail.tsx lines 171-175 before unioning
identity?.primaryLabel with cls?.deviceType. Ensure axisFacts,
detectAxisConflict, deviceTypeColor, and deviceTypeIcon receive actual
DeviceType codes; no direct change is needed elsewhere.

[coderabbitai]

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Duplicate media query.

The @media (max-width: 700px) { .cd-groups … } rule is emitted twice back to back; drop one.

🧹 Remove the duplicate

 `@media` (max-width: 700px) { .cd-groups { grid-template-columns: 1fr; } }
-@media (max-width: 700px) { .cd-groups { grid-template-columns: 1fr; } }

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In
`@frontend/src/components/conversation/ConversationDetail/ConversationDetail.css`
at line 161, Remove the duplicate `@media` (max-width: 700px) rule for .cd-groups
in ConversationDetail.css, keeping a single rule with grid-template-columns:
1fr.

[NotYuSheng]

Thanks @coderabbitai — addressed the findings in 281e311:

Fixed

• Race-safe lazy adjudication (Major) — HostIdentityEvidenceService now catches DataIntegrityViolationException from a concurrent first-read and re-reads the winner's rows, mirroring HostIdentitiesController. Also collapsed the double findByFileId into one load.
• primaryLabel cast to DeviceType (Major) — the ConversationDetail flow chip no longer casts a HUMAN label (free text like "Bob's Laptop") to DeviceType; it falls back to the machine classification's deviceType for the icon/colour. (The toNodeData cast already guards HUMAN → undefined, so machine verdicts there are always codes.)
• Host cards clickable without fileId (Minor) — cards now render non-interactive (plain div, no "open" hint) when there's no fileId.
• Stale identity chips after in-modal override (Minor) — the flow-header identity map refetches when the host modal closes.
• EntityDetailModal fileId guard (Minor) — HostIdentitySection now gated on fileId, matching sibling sections.
• a11y — aria-hidden on the decorative chevron, warning, and contested icons; the host-card "open" hint now also reveals on :focus-visible.
• Copy — "evidence axes below" → "in this panel".
• Split .cd-host-role declarations — merged into one block.
• Stale NodeDetails comment — removed.

Follow-up issue

• Scoping the flow-header identity fetch to the two endpoint IPs (instead of the whole file) is tracked in Scope conversation flow-header identity fetch to the two endpoint IPs #576 — kept out of this PR to stay scoped; no correctness impact.

Already resolved / N/A

• Duplicate @media (max-width: 700px) rule — only one instance in the current file; no change needed.

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

@NotYuSheng Thanks for the thorough follow-up. The fixes in 281e311 address the reported correctness, interaction, accessibility, and stale-state concerns.

Keeping the endpoint-only identity fetch optimization scoped to #576 is reasonable.

🐇 ✅

---

✏️ Learnings added

Learnt from: NotYuSheng
URL: https://github.com/NotYuSheng/TracePcap/pull/575

Timestamp: 2026-07-26T05:18:30.612Z
Learning: For the conversation flow-header identity map in `frontend/src/components/conversation/ConversationDetail/ConversationDetail.tsx`, restricting the host identity fetch to only the two endpoint IPs is intentionally deferred to GitHub issue `#576`; the current whole-file fetch has no correctness impact.

Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.

---

If you found this review helpful, would you consider giving us a shout-out on X?

Thank you for using CodeRabbit!