GitHub - ShantanuKudva/trafficVisualizer-v2: One globe, many visuals · GitHub
Skip to content

About

One globe, many visuals

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository
BranchesTags

Repository files navigation

Globe Visualization V2 - Documentation

Last Updated: December 9, 2025 19:36 IST

Overview

Globe Visualization V2 is a universal, plugin-driven geo-visualization platform built with Next.js, Three.js, and React. It transforms location data into immersive 3D globe visualizations, supporting multiple data types through a flexible plugin architecture.

Core Capabilities

  • Universal Platform: Data-agnostic rendering engine supporting any geographic data
  • Plugin Architecture: Extensible system with 3 reference plugins (Network Traffic, HawkNet Server, Robot Fleet)
  • JSON Dashboard Engine: Declarative, config-driven sidebar panels for node details (Grafana-style widgets)
  • Real-Time + Historical: 24-hour rolling window for forensic analysis with live auto-refresh
  • Time-Reactive UI: Sidebar panels update in real-time when time slider changes
  • High Performance: 60fps target, <300MB memory, supports 1000+ concurrent objects

Documentation Status

✅ Phase 0: Analysis (Complete)

Location: /docs/00-analysis/

Document Status Description
UNDERSTANDING.md ✅ Complete V1 architecture analysis and reverse engineering
ISSUES.md ✅ Complete Critical bugs, root cause analysis, and test cases
TECHNOLOGY_REVIEW.md ✅ Complete Technology stack evaluation and recommendations

✅ Phase 1: Requirements (Complete)

Location: /docs/01-requirements/

Document Status Description
PRD.md ✅ Complete Product vision, target users, key features, workflows
USER_STORIES.md ✅ Complete 13 user stories across 5 epics, 108 story points
FUNCTIONAL_REQUIREMENTS.md ✅ Complete 20 functional requirements (FR-001 to FR-020)
NON_FUNCTIONAL_REQUIREMENTS.md ✅ Complete Performance, security, reliability, usability targets
API_REQUIREMENTS.md ✅ Complete Generic plugin adapter + 3 concrete API specs

Key Deliverables:

  • Platform-first approach with 3 concrete use cases
  • Plugin capability system (supportsHistorical, supportsLive, requiresTimeControl)
  • Live mode = 24-hour rolling window (not just current moment)
  • 5-minute bucketing with 30-second overlap strategy

✅ Phase 2: High-Level Architecture (Complete)

Location: /docs/02-architecture/

Document Status Description
HLD_OVERVIEW.md ✅ Complete System architecture, 5-layer design, technology choices
HLD_DATA_FLOW.md ✅ Complete Historical/live/multi-plugin patterns, bucketing, caching
HLD_STATE_MANAGEMENT.md ✅ Complete Zustand + React Query hybrid approach
HLD_RENDERING_PIPELINE.md ✅ Complete Three.js setup, 3 plugin renderers, instanced rendering
HLD_TYPE_SYSTEM.md ✅ Complete Universal GeoDataPoint contract, plugin interfaces
HLD_EXTENSIBILITY.md ✅ Complete 4 extension points, Supply Chain plugin example

Key Deliverables:

  • 5-layer architecture (Presentation, Core, Data, External APIs, Rendering)
  • Zustand (UI state) + React Query (server state) separation
  • Three.js with React Three Fiber (R3F) for 3D visualization
  • Debouncing strategy (300ms time slider = 99%+ request reduction)
  • Cache invalidation: selective bucket invalidation + stale-while-revalidate

✅ Phase 3: Low-Level Detailed Design (Complete)

Location: /docs/03-detailed-design/

Document Status Description
LLD_DATA_TYPE_REGISTRY.md ✅ Complete Plugin registration with Zod validation, O(1) operations
LLD_BUCKETING_ENGINE.md ✅ Complete 5-min buckets, 30s overlap, hash deduplication, <25MB
LLD_GLOBE_RENDERER.md ✅ Complete Three.js scene, 64×64 sphere, OrbitControls, PBR lighting
LLD_VISUALIZATION_ENGINE.md ✅ Complete Renderer orchestration, raycasting, multi-plugin support
LLD_DATA_STREAM_MANAGER.md ✅ Complete Debounced fetching, live 5s refresh, parallel multi-plugin
LLD_TIME_CONTROLLER.md ✅ Complete Playback controls (1x-10x), bucket snapping, time bounds
LLD_API_CLIENT.md ✅ Complete HTTP wrapper, exponential backoff retry, Zod validation
LLD_STATE_MANAGER.md ✅ Complete Zustand store with persistence middleware
LLD_CONFIGURATION_MANAGER.md ✅ Complete Environment variable loading, singleton pattern
LLD_UTILS.md ✅ Complete Geo conversion, date formatting, math helpers

Key Deliverables:

  • Complete class structures with TypeScript interfaces
  • Detailed algorithms with step-by-step pseudocode
  • Error handling strategies with graceful degradation
  • Comprehensive testing strategies (unit + integration)
  • Performance analysis (time/space complexity, memory estimates)

✅ Phase 4: Interface Contracts (Complete)

Location: /docs/04-interfaces/

Document Status Description
API_CONTRACTS.md ✅ Complete External API endpoint specifications
INTERNAL_INTERFACES.md ✅ Complete Internal module interface contracts
TYPE_DEFINITIONS.md ✅ Complete TypeScript type definitions and schemas
DATA_SCHEMAS.md ✅ Complete Zod schemas for runtime validation
EVENT_CONTRACTS.md ✅ Complete Event system specifications

Key Deliverables:

  • External API contracts for 3 plugins (Network, Server Infrastructure, Robot Fleet)
  • Internal module interfaces with dependency graph
  • 40+ TypeScript type definitions organized by domain
  • Comprehensive Zod validation schemas
  • 15 event contracts with publishers, subscribers, and payloads

✅ Phase 5: Architectural Decisions (Complete)

Location: /docs/05-decisions/

Document Status Description
ADR_INDEX.md ✅ Complete Index of 8 architectural decisions by impact
ADR_001_BUCKETING.md ✅ Complete 5-minute buckets with 30-second overlap decision
ADR_002_MODULARITY.md ✅ Complete Plugin-driven architecture rationale
ADR_003_STATE.md ✅ Complete Zustand + React Query hybrid approach
ADR_004_RENDERING.md ✅ Complete Three.js + React Three Fiber selection
ADR_005_API_STRATEGY.md ✅ Complete RESTful API with adapter pattern
ADR_006_ERROR_HANDLING.md ✅ Complete Result type for expected failures
ADR_007_TESTING.md ✅ Complete Vitest + Playwright testing strategy
ADR_008_BUILD_TOOLS.md ✅ Complete Next.js 16 + React 19 + R3F 9

Key Deliverables:

  • 8 comprehensive ADRs with context, alternatives, consequences
  • Evaluated 4+ alternatives for each major decision
  • Decision criteria clearly documented
  • Cross-references to related documentation
  • Future review dates specified

✅ Phase 6: Implementation Planning (Complete)

Location: /docs/06-implementation/

Document Status Description
IMPLEMENTATION_PLAN.md ✅ Complete Master implementation roadmap with TDD approach
TESTING_STRATEGY.md ✅ Complete Comprehensive TDD methodology and testing pyramid
PHASE_1_FOUNDATION.md ✅ Complete Days 1-2: Next.js 16 setup, testing infrastructure, utilities
PHASE_2_DATA_LAYER.md ✅ Complete Days 3-5: BucketingEngine, API Client, State Management
PHASE_3_RENDERING.md ✅ Complete Days 6-8: Three.js, Globe, Visualization Engine
PHASE_4_UI.md ✅ Complete Days 9-11: Time Controller, Plugins, UI Components
PHASE_5_INTEGRATION.md ✅ Complete Days 12-14: E2E testing, performance tuning, production build
DEPLOYMENT_PLAN.md ✅ Complete Deployment strategy, CI/CD, monitoring, security

Key Deliverables:

  • Test-Driven Development (TDD) methodology with Red-Green-Refactor cycle
  • 285+ tests (unit, integration, E2E) across all phases
  • 85%+ test coverage requirement enforced
  • Performance targets: 60fps, < 300MB memory, < 2s load
  • Visual regression testing suite (6 baseline states)
  • CI/CD pipeline with GitHub Actions
  • Multi-platform deployment options (Vercel, AWS, Self-Hosted)
  • Comprehensive monitoring and security checklist

📋 Phase 7: Future Roadmap

Location: /docs/07-roadmap/

Document Status Description
FUTURE_SCOPE.md 📋 Index Roadmap index and prioritization
MCP_SERVER.md 📋 Planned AI/LLM-driven visualization
PLUGIN_SDK.md 📋 Planned Third-party plugin development
NETWORK_ORCHESTRATOR.md 📋 Planned Multi-scale NOC topology
PACKAGE_EXTRACTION.md 📋 Planned NPM package publishing
LOD_CLUSTERING.md 📋 Planned Zoom-based clustering system
EXPORT_SHARING.md 📋 Planned Screenshots, videos, sharing
OFFLINE_MAPS.md 📋 Planned Air-gap deployment support
COLLABORATIVE_EDITING.md 📋 Planned Multi-user sessions
AR_VR_MODE.md 📋 Planned WebXR immersive mode

Technology Stack

Frontend

  • Framework: Next.js 16.0.1 (App Router)
  • Language: TypeScript 5
  • UI: React 19.2.0, Tailwind CSS 4, shadcn/ui
  • 3D Rendering: Three.js 0.181.0, React Three Fiber 9.4.0
  • State: Zustand 5.0.8 (UI), TanStack Query 5.90.6 (server state)
  • Validation: Zod 3.23+
  • Testing: Vitest 2.1.8 (unit), Playwright 1.49 (E2E)

Backend APIs (External)

  • Network Traffic API: /api/analytics/geo-flows
  • Server Infrastructure API: /api/infrastructure/servers
  • Robot Fleet API: /api/fleet/robots

Project Structure

v2/
├── docs/                           # All documentation
│   ├── 00-analysis/               # V1 analysis and issues
│   ├── 01-requirements/           # PRD, user stories, requirements
│   ├── 02-architecture/           # High-level design
│   ├── 03-detailed-design/        # Low-level module specs
│   ├── 04-interfaces/             # Contracts
│   ├── 05-decisions/              # ADRs
│   └── 06-implementation/         # Implementation plans
├── src/                           # Source code (not yet written)
│   ├── app/                       # Next.js App Router
│   ├── components/                # React components
│   ├── core/                      # Core modules (Registry, Bucketing)
│   ├── rendering/                 # Three.js renderers
│   ├── plugins/                   # Plugin implementations
│   ├── api/                       # API clients
│   ├── state/                     # Zustand stores
│   ├── utils/                     # Utilities
│   └── types/                     # TypeScript types
├── tests/                         # Test files (pending)
└── README.md                      # This file

Key Design Decisions

1. Platform-First Approach

Decision: Build a universal geo-visualization platform, not a network-specific tool
Rationale: Enables reuse across multiple domains (networking, infrastructure, IoT, supply chain)
Reference: PRD.md

2. Plugin Architecture

Decision: Data sources implemented as plugins with standardized interfaces
Rationale: Extensibility, separation of concerns, zero core changes for new data types
Reference: HLD_TYPE_SYSTEM.md

3. 24-Hour Rolling Window

Decision: Live mode shows last 24 hours (not just current moment)
Rationale: Enables forensic analysis (e.g., "Flow A triggered Flow B at 10:17")
Reference: HLD_DATA_FLOW.md

4. 5-Minute Bucketing with 30-Second Overlap

Decision: Aggregate data into 5-minute buckets with 30-second overlap
Rationale: Balances granularity, performance, and boundary coverage
Reference: LLD_BUCKETING_ENGINE.md

5. Debounced Time Slider

Decision: 300ms debounce on timestamp updates
Rationale: Reduces network requests by 99%+ during scrubbing (60fps × 2s = 120 requests → 1 request)
Reference: HLD_DATA_FLOW.md

Development Workflow

Documentation-First Approach

Critical Rule: ❌ NO CODE until all documentation phases approved

  1. Phase 0-6: Design, specification, decisions, and planning (✅ COMPLETE)
  2. Implementation: Code only after Phase 6 approval

Update Process

When adding new content:

  1. Create/update relevant documentation
  2. Update this README.md table of contents
  3. Update timestamp at top of this file
  4. Mark items as complete (✅) or in-progress (🔄)

Performance Targets

Metric Target Status
Frame Rate 60 FPS 📋 Specified
Initial Load < 2 seconds 📋 Specified
Memory Usage < 300 MB 📋 Specified
Data Retention 24 hours 📋 Specified
Concurrent Arcs 1000+ 📋 Specified
Concurrent Markers 500+ 📋 Specified
Bucketing Performance < 100ms for 10k points 📋 Specified

Plugin Capabilities

Plugin Historical Live Time Control Visualization
Network Traffic ✅ Yes ✅ Yes ✅ Yes Animated arcs, city markers
HawkNet Server Infrastructure ✅ Yes ✅ Yes ✅ Yes Server nodes, hub connections
Robot Fleet ❌ No ✅ Yes ❌ No Robot markers, facility view

JSON Dashboard Engine (New)

The platform now includes a JSON-driven dashboard engine for node detail panels:

  • Declarative Configuration: Define layouts in dashboardLayouts.ts
  • Widget Types: Health Gauge, Connectivity Grid, Hub Connection, Protocol Bars, Node Info, Destination List, Applications List, Policy Violations, Country Breakdown, Top IPs
  • Full V1 Parity: Matches v1 design for both Network (Dot) and HawkNet (Server) panels
  • Time-Reactive: Panels re-render when time slider changes

Quick Links

Requirements

Architecture

Implementation Specs

Contributing

This project follows a strict documentation-first development process:

  1. All design decisions must be documented before implementation
  2. Each phase requires explicit approval before proceeding to the next
  3. Code changes must reference relevant documentation sections
  4. Test coverage targets: 85%+ for all modules

License

TBD

Contact

For questions or clarifications, refer to the documentation structure above or reach out to the project maintainers.

Document Version: 1.0
Last Updated: December 7, 2025 12:41 IST
Documentation Status: Phase 0-6 Complete, Ready for Implementation

About

One globe, many visuals

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages