Introducing a new way to review your PRs.

Read the announcement

lockfale / osint-framework

OSINT Framework

View on GitHub

8 documents · Updated Nov 16, 2026

docs / public-osint-explorer-ui

Public OSINT Explorer UI

Overview

The browser explorer is a static HTML shell in public/index.html plus the client script in public/…/arf.js, rendered with the vendored D3 v7.9.0 bundle at public/…/d3.min.js. The page loads css/arf.css and css/panel.css before D3, then executes js/arf.js after the header, search box, tool details panel, and rating/reporting controls already exist in the DOM.

On startup, public/index.html applies body.light-mode immediately when localStorage.theme is light, preventing a theme flash before the graph code reads CSS variables. It then provides the permanent DOM anchors that public/…/arf.js expects: #body for SVG insertion, #search-input and #search-results for client-side search, #tool-panel and #panel-overlay for tool metadata, hidden .legend/#notes-content content used to populate the notes drawer, and #notes-panel/#notes-overlay for the notes UI. The HTML also wires simple inline click handlers for theme and notes controls (goDark() and toggleNotesPanel()), so those function names are part of the page contract.

public/…/arf.js appends an SVG to #body, creates a D3 tree layout (d3.tree()), horizontal link generator (d3.linkHorizontal()), and zoom behavior (d3.zoom()), then loads arf.json with d3.json("arf.json"). The JSON is converted to a d3.hierarchy, filtering null children, and every node with data.url is captured in allSearchNodes for search. Initial state collapses all root children into _children, computes an aspect-ratio-aware SVG viewBox, lays out visible nodes at fixed depth spacing (d.y = d.depth * 180), applies an initial zoom-to-fit transform, then calls update(root) and initSearch().

Graph rendering is centralized in update(source) in public/…/arf.js. It recomputes the tree, binds root.descendants().reverse() to g.node groups keyed by generated d.id, and binds root.links() to path.link elements keyed by target id. Entering nodes start at the source's previous position, then transition over duration (1250 ms) to their computed positions; exiting nodes and links transition back toward the source. Node circles use CSS variables read via getCSSVar() for branch/leaf fills, highlighted search state, and selected-panel stroke. Text labels split suffix badges like (T), (D), (R), and (M) with parseName() so the clean name and colored inline suffixes can be rendered separately.

Interaction state lives directly on D3 hierarchy nodes. Expanding/collapsing moves children between children and _children in toggle(d). Clicking a non-leaf or collapsed node toggles it and re-renders; clicking a terminal URL node opens the details panel instead of navigating directly. Search state uses _highlighted flags and the global searchMatches; panel selection uses _panelSelected plus _panelNode. Because these flags are stored on hierarchy nodes, any code that rebuilds root from JSON will reset UI state.

Search is entirely client-side in public/…/arf.js. initSearch() debounces input by 200 ms and delegates result clicks/Enter keypresses from #search-results. doSearch(query) lowercases the query, matches against each URL node's name and description, caps results at 50, escapes names/paths, and only exposes external-link anchors for http/https URLs accepted by safeUrl(). Selecting a result calls revealNode(d), which collapses the whole tree, expands the selected node's ancestors, highlights the target, updates the graph, pans to the node with zoomToNode(d), and clears the dropdown/input.

The details panel is populated by openPanel(d) in public/…/arf.js using the static panel markup in public/index.html and styles in public/…/panel.css. It derives the display name and T/D/R/M badges from parseName(d.data.name), builds breadcrumbs from ancestors, and reads enrichment fields from the JSON node: description, status, pricing, api, invitationOnly, deprecated, nsfw, region, bestFor, input, output, opsec, and opsecNote. Empty optional sections receive an .empty class so public/…/panel.css hides them. Opening a tool also creates a session id in sessionStorage.osint-session when crypto.randomUUID() is available, shows the slide-in panel and overlay, and re-renders the graph to show the selected stroke.

The panel also owns three browser-to-server interactions. The “Open Tool” CTA sets a safe URL and, on click, sends a fire-and-forget navigator.sendBeacon() JSON payload to /api/track with tool_id, session_hash, and timestamp. _renderVoteUI(d) reads the user's cached sessionStorage rating for rating:<toolId>, fetches live stats from /api/tool-stats?tool_id=..., and lets users cast/toggle half-star ratings through POST /api/vote. _resetReportButtons(d) wires the footer report buttons to POST /api/report with a report_type of dead_link, paywalled, or incorrect_info; buttons are disabled while the request is in flight and re-enabled only on failure. These calls are best-effort client behavior: failures are caught locally and do not affect graph navigation.

Theme and notes behavior are also handled in public/…/arf.js. goDark() toggles body.light-mode, persists localStorage.theme, updates the header button label, and calls update(root) so D3 inline colors refresh from the new CSS variables. toggleNotesPanel() opens the notes drawer, toggles #notes-overlay.visible, and lazily copies .legend plus #notes-content HTML into #notes-panel-body the first time it opens. Escape closes the notes panel if it is open, otherwise it closes the tool panel; the SVG background click also closes the tool panel.

Styling is split by responsibility. public/…/arf.css defines the design tokens, dark/light theme variables, base page layout, SVG sizing, header actions, graph node/link defaults, badge colors, search dropdown, and notes drawer/mobile notes button behavior. public/…/panel.css styles the tool details panel, panel overlay, metadata sections, CTA, rating stars, report footer, enrichment badge pills, and the mobile full-screen panel. D3-rendered nodes receive some final colors and stroke widths as inline styles from public/…/arf.js, so changes to theme variables require a graph re-render to appear on existing nodes.

Routing / ownership

  • public/index.html owns the browser shell, script/style ordering, persistent DOM ids, inline bootstrapping for theme preference, static panel/search/notes markup, and legend content.
  • public/…/arf.js owns data loading from arf.json, D3 tree/zoom rendering, expand/collapse state, search/reveal behavior, panel population, client rating/reporting/tracking calls, theme toggling, and notes drawer behavior.
  • public/…/d3.min.js is the vendored D3 v7.9.0 runtime that provides the d3 global used by public/…/arf.js; it is not application logic.
  • public/…/arf.css owns design tokens, page layout, graph/search/notes styles, theme variables, and responsive behavior outside the tool details panel.
  • public/…/panel.css owns the tool details panel, enrichment badges, CTA, rating/reporting controls, overlay behavior, and mobile panel layout.

Coupling

  • If any id or class in public/index.html is renamed, verify public/…/arf.js, public/…/arf.css, and public/…/panel.css together. The script looks up fixed ids such as #body, #search-input, #search-results, #tool-panel, #panel-open-tool, #star-rating, .report-btn, #notes-content, and .legend; missing elements usually degrade silently because many handlers return early.
  • If the arf.json tool schema changes, update public/…/arf.js panel/search rendering and the matching public/…/panel.css badge styles. openPanel(d) reads enrichment fields directly by name and falls back only for some values (status, pricing, opsec, region), so renamed fields disappear from the UI without a schema validation error.
  • If theme tokens in public/…/arf.css change, verify getCSSVar() usage in public/…/arf.js. Existing D3 nodes keep inline styles until update(root) runs, which is why goDark() explicitly re-renders after toggling body.light-mode.
  • If rating, reporting, or tracking API payloads change, update public/…/arf.js and the static controls in public/index.html together. The browser sends /api/tool-stats, /api/vote, /api/report, and /api/track payloads with tool_id based on parseName(d.data.name).cleanName, not a separate immutable id.
  • If public/…/d3.min.js is replaced or upgraded, verify public/…/arf.js against the D3 v7 APIs it uses: d3.tree, d3.linkHorizontal, d3.zoom, d3.zoomIdentity, d3.hierarchy, d3.json, event callback signatures, selections, transitions, and d3.zoomTransform.

Risks

  • public/…/arf.js derives tool_id from the display name after stripping (T)/(D)/(R)/(M) suffixes. If two tools share the same clean name, /api/tool-stats, /api/vote, /api/report, /api/track, and sessionStorage rating keys collide, causing ratings/reports/tracking to be attributed to the wrong visible tool.
  • public/…/arf.js assigns panel/report/rating handlers each time openPanel(d) runs and stores the current tool only in closures and _panelNode. If future changes reuse those controls outside openPanel() or mutate d.data.name after opening, the visible panel can send actions for a stale toolId.
  • public/index.html calls goDark() and toggleNotesPanel() from inline onclick attributes. If public/…/arf.js is loaded with module scope or deferred behind a bundler that does not expose globals, the header and mobile buttons stop working even though the DOM and CSS still render.