NET NiNjA v1.2

Overview

NET NiNjA is a local-first network dashboard that combines a Ktor-based server, a Web UI, and an Android WebView shell. The Android app boots a local server, serves the bundled web assets, and loads the dashboard directly in a WebView so the same UI can run both on-device and in a desktop browser during development.

What it does (functions & capabilities)

• Local Web UI: Serves the dashboard UI from /ui on the local server, with the default entry at http://127.0.0.1:8787/ui/ninja_mobile_new.html.
• Android WebView shell: Launches ninja_mobile_new.html from bundled assets, then switches to the local server once it is ready. This keeps the UI responsive while the server is starting and avoids file-scheme fetch limitations.
• Asset sync for consistent UI: The packaged Web UI assets are synced into the app’s internal storage and served by the local server so WebView always loads the same bundle.
• Safe WebView defaults: JavaScript and DOM storage are enabled, cache is cleared and disabled on boot, and the UI is served from a local-only origin (127.0.0.1).
• Diagnostics: WebView console errors are logged and JS errors are captured by window.onerror for easier debugging during development.

Primary use cases

• Android deployment: Package the Web UI and local server in the Android app to run an on-device dashboard.
• Local dev: Run the Ktor server directly and open the Web UI in a browser for faster iteration.
• Offline-friendly UX: Load the bundled dashboard UI immediately so the app isn’t blank while the local server is warming up.

Architecture at a glance

• Server: Ktor-based local server (runs on 127.0.0.1:8787) that serves /ui/*.
• Web UI: Static HTML/CSS/JS under web-ui/, including the mobile dashboard in web-ui/.
• Android app: WebView wrapper that syncs web-ui/ assets into internal storage and then loads the local server URLs.

3D Discovery Map (Ninja Nodes)

The Discovery Map is an interactive 3D network visualization embedded directly in the dashboard's Networks tab. It renders every discovered device as a floating node in a fully rotatable, zoomable 3D space with real-time link animations, data-beam effects, and threat highlighting — all running on a pure HTML5 Canvas engine (no WebGL library required).

Highlights

• Six color themes: Cyber, Matrix, Aurora, Solar, Ice, and Ghost — switch on the fly via the toolbar or theme swatches.
• Five layout modes: Star, Ring, Mesh, Tree, and Cluster topologies arrange nodes automatically based on the active device list.
• HUD overlay system: Draggable, minimizable panels for Activity Feed, Compass, Zoom indicator, Device Legend, and Map Coordinates.
• Visual effects toolbar: Toggle particles, data beams, heatmap overlays, device labels, and background grid independently.
• Touch-first interaction: Drag to orbit, pinch to zoom, tap a node for a detailed tooltip (IP, MAC, vendor, trust level), and momentum-based inertia after release.
• Live scan integration: The Scan button triggers a radar-sweep animation and the map auto-refreshes when new devices appear.
• External API: Call window.nnUpdateDiscoveryMap(deviceList) from any script to feed live device data into the visualization.

The standalone page lives at web-ui/new_assets/ninja_nodes.html and is loaded into the dashboard via an iframe for full isolation and zero CSS/JS conflicts.

Quick start

Run the server (Gradle)

./gradlew :server:run

Then open: http://localhost:8787/ui/ninja_mobile_new.html

Run with Docker

docker-compose up --build

Then open: http://localhost:8787/ui/ninja_mobile_new.html

Deployment (Desktop/server)

See docs/DEPLOYMENT.md for:

• environment variables
• database migrations
• backup/restore
• monitoring/alerting notes
• performance tuning notes

Web UI entry points

• Dashboard: http://127.0.0.1:8787/ui/ninja_mobile_new.html

Repo layout (high level)

• android-app/: Android WebView app and local server bootstrapping.
• server/: Ktor server module.
• web-ui/: Static web assets (HTML/CSS/JS).
• docs/: Implementation notes and WebView hardening details.

Contributing & security

• See CONTRIBUTING.md and SECURITY.md.