dennii/Termix
1
0
Fork 0
Code Issues Pull Requests 2 Actions Packages Projects Releases 22 Wiki Activity

Feature request: Network graph #442

Closed
SteveJos wants to merge 5 commits from feature/add-network-graph into dev-1.10.0
pull from: feature/add-network-graph
merge into: dennii:dev-1.10.0
Conversation 8 Commits 5 Files Changed 21 +3153 -3839
SteveJos commented 2025-12-07 19:58:57 +00:00 (Migrated from github.com)
Copy Link

Overview

This PR introduces a complete Network Graph visualization system to Termix, allowing users to interactively visualize, manage, and organize their SSH hosts and connections in an intuitive graph interface powered by Cytoscape.js. The feature is integrated into the Dashboard and can be toggled between the traditional "Recent Activity" view. It includes full persistence, export/import capabilities, and advanced node management with grouping support.

Added

  • Network Graph Visualization Component (src/ui/desktop/dashboard/network-graph/NetworkGraphView.tsx)

    • Interactive graph rendering using Cytoscape.js v3.33.1 with force-directed layout algorithm
    • Real-time host status indicators (Online/Offline/Unknown) with color-coded nodes
    • Support for organizational grouping with customizable colors
    • Automatic and manual node positioning with layout controls
    • Context menu for quick actions (connect, edit, move, delete)
    • Comprehensive error handling and loading states

  • Backend Network Topology API (src/backend/database/routes/network-topology.ts)

    • GET endpoint for fetching saved topology for authenticated users
    • POST endpoint for saving/updating topology with proper error handling
    • Uses Drizzle ORM with SQLite for secure persistence
    • Proper authentication middleware integration

  • Database Schema (src/backend/database/db/schema.ts)

    • New networkTopology table with userId foreign key reference
    • Fields: id, userId, topology (JSON text), createdAt, updatedAt
    • Cascade delete on user removal
    • Automatic schema migration on startup

  • Frontend API Functions (src/ui/main-axios.ts)

    • getNetworkTopology() - Fetches saved topology via GET
    • saveNetworkTopology(topology) - Saves topology via POST with data cleaning
    • Enhanced host fetching with status integration (getSSHHosts() now returns SSHHostWithStatus)
    • Proper TypeScript interfaces for type safety

  • Node Management Features

    • Add SSH hosts to topology (filtered to show only available hosts)
    • Create bidirectional connections between nodes
    • Remove nodes and connections with delete button
    • Move nodes between groups
    • Real-time node status updates every 30 seconds
    • Drag-and-drop node repositioning with auto-save

  • Graph Controls

    • Zoom In/Out buttons for detail work
    • Fit to Screen to view entire topology
    • Auto-Layout button to reorganize graph using force-directed algorithm
    • Pan and zoom with mouse wheel support

  • Data Management

    • Export topology as JSON file for backup/sharing
    • Import previously saved topology files
    • Debounced automatic saves on node position changes
    • Data validation and error recovery with graceful fallbacks

  • Host Detail Viewer

    • Click nodes to view comprehensive host information
    • Display name, IP address, port, status, and tags
    • Read-only details modal for quick reference

  • Group/Folder Management (Advanced)

    • Create organizational groups to categorize hosts
    • Edit group names and colors
    • Move hosts between groups
    • Context menu for group operations

  • Dashboard Integration

    • Toggle button to switch between Network Graph and Recent Activity views
    • Conditional title and icon changes based on active view
    • Graph displays by default on Dashboard
    • Status legend showing Online/Offline indicators

  • Tab System Support

    • Network Graph can be opened as separate tab
    • Full tab context integration with title tracking
    • Icon support in tab dropdown and navigation

  • Standalone Apps

    • HostManagerApp.tsx - Fullscreen host manager
    • NetworkGraphApp.tsx - Fullscreen network graph view
    • Query parameter support for launching specific views (?view=network-graph)

  • Dependencies Added

    • cytoscape@^3.33.1 - Graph visualization library
    • react-cytoscapejs@^2.0.0 - React wrapper for Cytoscape
    • @types/cytoscape@^3.21.9 - TypeScript type definitions

Updated

  • Dashboard Component (src/ui/desktop/apps/dashboard/Dashboard.tsx)

    • Added showNetworkGraph state to toggle between views
    • Conditional rendering of NetworkGraphView vs RecentActivity
    • Updated title rendering with Network icon when graph is active
    • Show Graph/Show Activity toggle button

  • Main App (src/main.tsx)

    • Added fullscreen view routing based on URL parameters
    • Support for ?view=host-manager and ?view=network-graph
    • FullscreenApp component to handle view routing

  • DesktopApp (src/ui/desktop/DesktopApp.tsx)

    • Added NetworkGraphView import
    • Added showNetworkGraph conditional rendering
    • Added tab context integration for network graph tabs
    • Auto-open terminal for hosts from URL parameters

  • Tab System (src/ui/desktop/navigation/tabs/Tab.tsx)

    • Added network_graph tab type support
    • Network icon for graph tabs
    • Full close/activate functionality for graph tabs

  • Tab Dropdown (src/ui/desktop/navigation/tabs/TabDropdown.tsx)

    • Added network_graph case handling
    • Network icon display in dropdown
    • Proper title localization fallback

  • Top Navbar (src/ui/desktop/navigation/TopNavbar.tsx)

    • Added network_graph tab type to split screen logic
    • Proper close button handling for graph tabs
    • Tab management integration

  • Nginx Configuration (both docker/nginx.conf and docker/nginx-https.conf)

    • Added /network-topology proxy route to backend server
    • Proper HTTP headers configuration (Host, X-Real-IP, X-Forwarded-For, X-Forwarded-Proto)
    • HTTP/1.1 compatibility settings

  • Backend Database (src/backend/database/database.ts)

    • Imported network-topology routes
    • Registered /network-topology route handler

  • Backend Database Initialization (src/backend/database/db/index.ts)

    • Added automatic schema migration for network_topology table
    • Handles creation if table doesn't exist
    • Proper error logging for migration issues

  • API Types (src/ui/main-axios.ts)

    • Added SSHHostWithStatus interface combining SSHHost with status field
    • Added NetworkTopologyData interface for topology structure
    • Extended axios config interfaces for request tracking
    • Improved TypeScript error handling in interceptors

  • README (README.md)

    • Added Network Graph View to feature list
    • Added comprehensive Network Graph View section documenting:
      • Features overview
      • Interactive capabilities
      • How to use guide
      • Limitations and notes
      • Performance recommendations

  • package.json & package-lock.json

    • Updated version to v1.9.0
    • Added cytoscape and react-cytoscapejs dependencies
    • Updated lock file with new dependencies and transitive deps

Screenshots / Demos

image image

Network Graph View Features:

  1. Interactive Nodes: Host boxes displaying name, IP, and tags

    • Green border = Online status
    • Red border = Offline status
    • Draggable for custom positioning
    • Click to view details
    • Right-click for context menu

  2. Control Toolbar:

    • Add Host (+) - Add SSH hosts to topology
    • Add Group (folder) - Create organizational groups
    • Add Connection (link) - Create edges between hosts
    • Delete (trash) - Remove selected node/connection
    • Auto-Layout - Force-directed graph reorganization
    • Zoom In/Out - Detail work controls
    • Reset View (rotate) - Fit entire graph
    • Export JSON - Backup topology
    • Import JSON - Restore topology
    • Open in Tab (external link) - Fullscreen view

  3. Graph Display:

    • Real-time status indicator badges
    • Force-directed layout with smooth animations
    • Context menu on right-click for quick actions
    • Selection highlighting with blue borders
    • Smooth bezier curves for connections

  4. Dashboard Integration:

    • Toggle between Graph/Activity views
    • Status legend (Online/Offline)
    • Integrated with existing Dashboard

Checklist

  • Code follows project style guidelines
  • Supports mobile and desktop UI/app (responsive canvas, touch-friendly controls)
  • TypeScript types properly defined
  • Error handling implemented with user feedback
  • Database persistence tested and working
  • API endpoints secured with authentication
  • All dependencies are production-ready
  • Documentation in README added
  • I have read Contributing.md

Testing Notes

  • Graph correctly loads and saves topology to database
  • Nodes display with accurate status indicators updated every 30 seconds
  • Export/import JSON functionality maintains topology integrity
  • Connections can be created, modified, and deleted
  • Manual node positioning persists across sessions
  • Groups can be created and managed
  • Context menu provides expected operations
  • Dashboard toggle switches correctly between views
  • Error states handled gracefully with user messages
  • Performance stable with 20-30 nodes (tested limit)
## Overview This PR introduces a complete Network Graph visualization system to Termix, allowing users to interactively visualize, manage, and organize their SSH hosts and connections in an intuitive graph interface powered by Cytoscape.js. The feature is integrated into the Dashboard and can be toggled between the traditional "Recent Activity" view. It includes full persistence, export/import capabilities, and advanced node management with grouping support. ## Added - **Network Graph Visualization Component** (`src/ui/desktop/dashboard/network-graph/NetworkGraphView.tsx`) - Interactive graph rendering using Cytoscape.js v3.33.1 with force-directed layout algorithm - Real-time host status indicators (Online/Offline/Unknown) with color-coded nodes - Support for organizational grouping with customizable colors - Automatic and manual node positioning with layout controls - Context menu for quick actions (connect, edit, move, delete) - Comprehensive error handling and loading states - **Backend Network Topology API** (`src/backend/database/routes/network-topology.ts`) - GET endpoint for fetching saved topology for authenticated users - POST endpoint for saving/updating topology with proper error handling - Uses Drizzle ORM with SQLite for secure persistence - Proper authentication middleware integration - **Database Schema** (`src/backend/database/db/schema.ts`) - New `networkTopology` table with userId foreign key reference - Fields: id, userId, topology (JSON text), createdAt, updatedAt - Cascade delete on user removal - Automatic schema migration on startup - **Frontend API Functions** (`src/ui/main-axios.ts`) - `getNetworkTopology()` - Fetches saved topology via GET - `saveNetworkTopology(topology)` - Saves topology via POST with data cleaning - Enhanced host fetching with status integration (`getSSHHosts()` now returns `SSHHostWithStatus`) - Proper TypeScript interfaces for type safety - **Node Management Features** - Add SSH hosts to topology (filtered to show only available hosts) - Create bidirectional connections between nodes - Remove nodes and connections with delete button - Move nodes between groups - Real-time node status updates every 30 seconds - Drag-and-drop node repositioning with auto-save - **Graph Controls** - Zoom In/Out buttons for detail work - Fit to Screen to view entire topology - Auto-Layout button to reorganize graph using force-directed algorithm - Pan and zoom with mouse wheel support - **Data Management** - Export topology as JSON file for backup/sharing - Import previously saved topology files - Debounced automatic saves on node position changes - Data validation and error recovery with graceful fallbacks - **Host Detail Viewer** - Click nodes to view comprehensive host information - Display name, IP address, port, status, and tags - Read-only details modal for quick reference - **Group/Folder Management** (Advanced) - Create organizational groups to categorize hosts - Edit group names and colors - Move hosts between groups - Context menu for group operations - **Dashboard Integration** - Toggle button to switch between Network Graph and Recent Activity views - Conditional title and icon changes based on active view - Graph displays by default on Dashboard - Status legend showing Online/Offline indicators - **Tab System Support** - Network Graph can be opened as separate tab - Full tab context integration with title tracking - Icon support in tab dropdown and navigation - **Standalone Apps** - `HostManagerApp.tsx` - Fullscreen host manager - `NetworkGraphApp.tsx` - Fullscreen network graph view - Query parameter support for launching specific views (`?view=network-graph`) - **Dependencies Added** - `cytoscape@^3.33.1` - Graph visualization library - `react-cytoscapejs@^2.0.0` - React wrapper for Cytoscape - `@types/cytoscape@^3.21.9` - TypeScript type definitions ## Updated - **Dashboard Component** (`src/ui/desktop/apps/dashboard/Dashboard.tsx`) - Added `showNetworkGraph` state to toggle between views - Conditional rendering of NetworkGraphView vs RecentActivity - Updated title rendering with Network icon when graph is active - Show Graph/Show Activity toggle button - **Main App** (`src/main.tsx`) - Added fullscreen view routing based on URL parameters - Support for `?view=host-manager` and `?view=network-graph` - FullscreenApp component to handle view routing - **DesktopApp** (`src/ui/desktop/DesktopApp.tsx`) - Added NetworkGraphView import - Added `showNetworkGraph` conditional rendering - Added tab context integration for network graph tabs - Auto-open terminal for hosts from URL parameters - **Tab System** (`src/ui/desktop/navigation/tabs/Tab.tsx`) - Added network_graph tab type support - Network icon for graph tabs - Full close/activate functionality for graph tabs - **Tab Dropdown** (`src/ui/desktop/navigation/tabs/TabDropdown.tsx`) - Added network_graph case handling - Network icon display in dropdown - Proper title localization fallback - **Top Navbar** (`src/ui/desktop/navigation/TopNavbar.tsx`) - Added network_graph tab type to split screen logic - Proper close button handling for graph tabs - Tab management integration - **Nginx Configuration** (both `docker/nginx.conf` and `docker/nginx-https.conf`) - Added `/network-topology` proxy route to backend server - Proper HTTP headers configuration (Host, X-Real-IP, X-Forwarded-For, X-Forwarded-Proto) - HTTP/1.1 compatibility settings - **Backend Database** (`src/backend/database/database.ts`) - Imported network-topology routes - Registered `/network-topology` route handler - **Backend Database Initialization** (`src/backend/database/db/index.ts`) - Added automatic schema migration for `network_topology` table - Handles creation if table doesn't exist - Proper error logging for migration issues - **API Types** (`src/ui/main-axios.ts`) - Added `SSHHostWithStatus` interface combining SSHHost with status field - Added `NetworkTopologyData` interface for topology structure - Extended axios config interfaces for request tracking - Improved TypeScript error handling in interceptors - **README** (`README.md`) - Added Network Graph View to feature list - Added comprehensive Network Graph View section documenting: - Features overview - Interactive capabilities - How to use guide - Limitations and notes - Performance recommendations - **package.json & package-lock.json** - Updated version to v1.9.0 - Added cytoscape and react-cytoscapejs dependencies - Updated lock file with new dependencies and transitive deps ## Screenshots / Demos <img width="1525" height="495" alt="image" src="https://github.com/user-attachments/assets/131388b3-101e-41fd-a129-7bcc10289cbe" /> <img width="1549" height="953" alt="image" src="https://github.com/user-attachments/assets/843ca844-f9d7-4a6a-8eda-e417d7525659" /> ### Network Graph View Features: 1. **Interactive Nodes**: Host boxes displaying name, IP, and tags - Green border = Online status - Red border = Offline status - Draggable for custom positioning - Click to view details - Right-click for context menu 2. **Control Toolbar**: - Add Host (+) - Add SSH hosts to topology - Add Group (folder) - Create organizational groups - Add Connection (link) - Create edges between hosts - Delete (trash) - Remove selected node/connection - Auto-Layout - Force-directed graph reorganization - Zoom In/Out - Detail work controls - Reset View (rotate) - Fit entire graph - Export JSON - Backup topology - Import JSON - Restore topology - Open in Tab (external link) - Fullscreen view 3. **Graph Display**: - Real-time status indicator badges - Force-directed layout with smooth animations - Context menu on right-click for quick actions - Selection highlighting with blue borders - Smooth bezier curves for connections 4. **Dashboard Integration**: - Toggle between Graph/Activity views - Status legend (Online/Offline) - Integrated with existing Dashboard ## Checklist - [x] Code follows project style guidelines - [x] Supports mobile and desktop UI/app (responsive canvas, touch-friendly controls) - [x] TypeScript types properly defined - [x] Error handling implemented with user feedback - [x] Database persistence tested and working - [x] API endpoints secured with authentication - [x] All dependencies are production-ready - [x] Documentation in README added - [x] I have read [Contributing.md](https://github.com/Termix-SSH/Termix/blob/main/CONTRIBUTING.md) ## Testing Notes - Graph correctly loads and saves topology to database - Nodes display with accurate status indicators updated every 30 seconds - Export/import JSON functionality maintains topology integrity - Connections can be created, modified, and deleted - Manual node positioning persists across sessions - Groups can be created and managed - Context menu provides expected operations - Dashboard toggle switches correctly between views - Error states handled gracefully with user messages - Performance stable with 20-30 nodes (tested limit)
LukeGus commented 2025-12-08 05:20:27 +00:00 (Migrated from github.com)
Copy Link

I like the idea, but the implementation requires significant improvement, primarily in the UI. It's obvious that the PR was AI-generated (or at least heavily involved), which I'm not against, but the code needs significant cleanup. These are the most obvious issues:

  • The network graph replaces the activity, which is not ideal since the recent activity is meant to be 1 click to connect, now its 2+.
  • The UI does not match the Termix UI at all. The colors are wrong on all UI elements, the borders are not consistent, rounding is off, for example:
image
  • JSON is exported in 1 line
  • Clicking on a host to edit it via the top header also opens another dialog, which is annoying
  • None of the buttons work inside the right-click context menu
  • Unneeded UI here that seems to serve no purpose:
image

Overall, I suggest you use it yourself before submitting the updates.

I like the idea, but the implementation requires significant improvement, primarily in the UI. It's obvious that the PR was AI-generated (or at least heavily involved), which I'm not against, but the code needs significant cleanup. These are the most obvious issues: - The network graph replaces the activity, which is not ideal since the recent activity is meant to be 1 click to connect, now its 2+. - The UI does not match the Termix UI at all. The colors are wrong on all UI elements, the borders are not consistent, rounding is off, for example: <img width="3496" height="1029" alt="image" src="https://github.com/user-attachments/assets/614aa33d-58df-41e4-8d6e-c10098112034" /> - JSON is exported in 1 line - Clicking on a host to edit it via the top header also opens another dialog, which is annoying - None of the buttons work inside the right-click context menu - Unneeded UI here that seems to serve no purpose: <img width="257" height="72" alt="image" src="https://github.com/user-attachments/assets/16cb22d6-2392-4e6c-a3a9-a15c081d73d9" /> Overall, I suggest you use it yourself before submitting the updates.
ZacharyZcR commented 2025-12-09 02:45:48 +00:00 (Migrated from github.com)
Copy Link

This is a great idea, and the AI implementation is quite well-developed. However, you'll need to adhere to our consistent design style and coding standards. If you wish to contribute, especially regarding feature requests like this one, I recommend reaching out to Discord and our development team for discussion. This will help ensure consistency in our work.

This is a great idea, and the AI implementation is quite well-developed. However, you'll need to adhere to our consistent design style and coding standards. If you wish to contribute, especially regarding feature requests like this one, I recommend reaching out to Discord and our development team for discussion. This will help ensure consistency in our work.
LukeGus commented 2025-12-20 02:14:00 +00:00 (Migrated from github.com)
Copy Link

Any update on the fixes @SteveJos?

Any update on the fixes @SteveJos?
SteveJos commented 2025-12-23 14:39:40 +00:00 (Migrated from github.com)
Copy Link

Hey @LukeGus and @ZacharyZcR! Thank you for the feedback! I will try to improve the points you mentioned, however time is a scarce commodity...
I will try to fix the PR in the next days!

Hey @LukeGus and @ZacharyZcR! Thank you for the feedback! I will try to improve the points you mentioned, however time is a scarce commodity... I will try to fix the PR in the next days!
LukeGus commented 2025-12-23 22:30:46 +00:00 (Migrated from github.com)
Copy Link

Sounds good. v1.10.0 is releasing within a couple days. If your able to fix it in time, it may be merged. Otherwise it will have to wait for a v1.10.x patch version.

Sounds good. v1.10.0 is releasing within a couple days. If your able to fix it in time, it may be merged. Otherwise it will have to wait for a v1.10.x patch version.
SteveJos commented 2025-12-30 17:21:14 +00:00 (Migrated from github.com)
Copy Link

@LukeGus I just now pushed the latest commit with the following changes:

  • Fixed:
    • UI design elemets
    • UI and button colors
    • JSON export
    • recent activity is default again
  • Removed:
    • Online/Offline UI labels
    • left-click menu on hosts
  • Added:
    • small pulsing dot inside the hosts to indicate online status like in the left bar

Please feel free to test the changes!

@LukeGus I just now pushed the latest commit with the following changes: - Fixed: - UI design elemets - UI and button colors - JSON export - recent activity is default again - Removed: - Online/Offline UI labels - left-click menu on hosts - Added: - small pulsing dot inside the hosts to indicate online status like in the left bar Please feel free to test the changes!
👍 1 🎉 1
LukeGus commented 2025-12-31 23:22:25 +00:00 (Migrated from github.com)
Copy Link

Thanks. I'll check it out and merge it for 1.10.1 in the next week or two.

Thanks. I'll check it out and merge it for 1.10.1 in the next week or two.
LukeGus commented 2026-01-01 06:02:48 +00:00 (Migrated from github.com)
Copy Link

Can you reopen this PR under the dev-1.10.1 branch? I deleted the old one and forgot that it would close the PR.

Can you reopen this PR under the `dev-1.10.1` branch? I deleted the old one and forgot that it would close the PR.
👍 1

Pull request closed

This pull request cannot be reopened because the branch was deleted.
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
Clear labels
bug
Something isn't working
 dependencies
Pull requests that update a dependency file
 docker
Pull requests that update docker code
 documentation
Improvements or additions to documentation
 duplicate
This issue or pull request already exists
 enhancement
New feature or request
 github_actions
Pull requests that update GitHub Actions code
 good first issue
Good for newcomers
 help wanted
Extra attention is needed
 invalid
This doesn't seem right
 javascript
Pull requests that update javascript code
 question
Further information is requested
 security
Questions about network security
 wontfix
This will not be worked on
No Label enhancement
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
dennii
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: dennii/Termix#442
Delete Branch "feature/add-network-graph"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?