{"id":41252903,"url":"https://github.com/bvandewe/topolizer","last_synced_at":"2026-01-23T01:43:22.795Z","repository":{"id":322375839,"uuid":"1089244309","full_name":"bvandewe/topolizer","owner":"bvandewe","description":"Visual network topology builder with drag-and-drop editing, export capabilities and multi-shape alignment tools","archived":false,"fork":false,"pushed_at":"2025-11-04T05:17:43.000Z","size":2299,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-04T06:18:46.395Z","etag":null,"topics":["cisco","diagram-builder","docker","fastapi","javascript","network-diagram","network-topology","svg","visualization"],"latest_commit_sha":null,"homepage":"https://bvandewe.github.io/topolizer/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bvandewe.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-04T04:42:05.000Z","updated_at":"2025-11-04T05:21:26.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/bvandewe/topolizer","commit_stats":null,"previous_names":["bvandewe/topolizer"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/bvandewe/topolizer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bvandewe%2Ftopolizer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bvandewe%2Ftopolizer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bvandewe%2Ftopolizer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bvandewe%2Ftopolizer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bvandewe","download_url":"https://codeload.github.com/bvandewe/topolizer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bvandewe%2Ftopolizer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28677711,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-23T01:00:35.747Z","status":"ssl_error","status_checked_at":"2026-01-23T01:00:19.529Z","response_time":144,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cisco","diagram-builder","docker","fastapi","javascript","network-diagram","network-topology","svg","visualization"],"created_at":"2026-01-23T01:43:22.327Z","updated_at":"2026-01-23T01:43:22.781Z","avatar_url":"https://github.com/bvandewe.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Topology Builder\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Release](https://img.shields.io/github/v/release/bvandewe/topolizer)](https://github.com/bvandewe/topolizer/releases)\n[![Docker](https://img.shields.io/badge/docker-ready-blue.svg)](https://github.com/bvandewe/topolizer/pkgs/container/topolizer)\n[![Build](https://github.com/bvandewe/topolizer/actions/workflows/docker-build-publish.yml/badge.svg)](https://github.com/bvandewe/topolizer/actions/workflows/docker-build-publish.yml)\n[![GitHub Pages](https://img.shields.io/badge/demo-live-success)](https://bvandewe.github.io/topolizer/)\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit)\n[![JavaScript](https://img.shields.io/badge/JavaScript-ES6+-yellow.svg)](https://developer.mozilla.org/en-US/docs/Web/JavaScript)\n[![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)](https://www.python.org/)\n\nA modern, interactive web-based network topology diagram builder with an intuitive drag-and-drop interface. Built with vanilla JavaScript, SASS, and FastAPI.\n\n**[🚀 Try the Live Demo](https://bvandewe.github.io/topolizer/)**\n\n![demo_v0.1.0](./docs/topolizer_v0.1.0.gif)\n\n## ✨ Features\n\n### 🎨 Interactive Canvas\n\n- **Infinite Canvas** with grid background and visual guides\n- **Zoom Support** (25% to 400%) for detailed work\n- **Pan/Scroll Navigation** for exploring large topologies\n- **Grid Snapping** for precise shape placement\n\n### 🔧 Shape Management\n\n- **Multiple Shape Types**:\n  - Basic shapes (circle, rectangle, ellipse)\n  - Cisco network devices (L2/L3 switches, routers, firewalls, access points, workstations, servers)\n- **Drag-and-Drop** shape creation from sidebar\n- **Visual Selection** with interaction circles\n- **Resize Handles** for shape modification\n- **Dynamic Interaction Circle** that scales with shape size\n- **Shape Labeling** with customizable:\n  - Text content\n  - Font size and color\n  - Position (above, below, left, right, center)\n- **Label Persistence** - Labels automatically move with shapes during drag operations\n- **Keyboard Support** - Delete/Backspace key to remove selected shapes\n\n### 🔗 Connection System\n\n- **Visual Connections** between shapes with smart routing\n- **Connection Labels** (source, target, and center)\n- **Draggable Labels** with circular constraint around shapes\n- **Line Styles** (solid, dashed, dotted)\n- **Connection Details Modal** for editing properties\n- **Automatic Updates** when shapes move\n\n### 💾 Data Persistence\n\n- **Auto-save** to browser localStorage\n- **Export/Import** topology as JSON\n- **State Preservation** including:\n  - Shape positions and sizes\n  - Connection labels and styles\n  - Zoom level and scroll position\n  - Label positions and constraint metadata\n\n### ⌨️ User Experience\n\n- **Keyboard Shortcuts**:\n  - `Enter` - Submit modal forms\n  - `Escape` - Close modals\n  - `Delete` / `Backspace` - Delete selected shape (with associated label and connections)\n- **Auto-focus** on input fields\n- **Visual Feedback** for all interactions\n- **Responsive Design** with Bootstrap 5.3\n- **Clean, Modern UI**\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- **Node.js** 18+ (for frontend)\n- **Python** 3.10+ (for backend)\n- **Poetry** (Python dependency management)\n\n### Installation\n\n1. **Clone the repository**\n\n   ```bash\n   git clone \u003crepository-url\u003e\n   cd ToplogyBuilder\n   ```\n\n2. **Backend Setup**\n\n   ```bash\n   # Install Poetry if not already installed\n   curl -sSL https://install.python-poetry.org | python3 -\n\n   # Install Python dependencies\n   poetry install\n   ```\n\n3. **Frontend Setup**\n\n   ```bash\n   cd frontend\n   npm install\n   cd ..\n   ```\n\n### Running the Application\n\n**Option 1: Integrated Server (Recommended)**\n\n```bash\n# From project root\n./start-server.sh\n```\n\nThis builds the frontend and starts the backend server with the application at:\n`http://localhost:8000`\n\n**Option 2: Separate Processes (Development)**\n\nTerminal 1 - Frontend build watch:\n\n```bash\ncd frontend\nnpm run watch\n```\n\nTerminal 2 - Backend server:\n\n```bash\ncd backend\npoetry run python main.py\n```\n\nAccess the application at: `http://localhost:8000`\n\n**Option 3: Frontend Only (for frontend development)**\n\n```bash\ncd frontend\nnpm run dev\n```\n\nFrontend dev server at: `http://localhost:1234`\n(Note: API features will require the backend to be running separately)\n\n**Option 4: Offline/Standalone Mode**\n\nFor environments without internet access or server requirements, you can use the standalone static build:\n\n```bash\n# Build the standalone package\n./build-offline-package.sh\n\n# Extract and open the generated zip file\nunzip topology-builder-offline-v*.zip\ncd topology-builder-offline\nopen index.html  # macOS\n# or double-click index.html in file explorer\n```\n\nThis creates a fully self-contained version that runs entirely in the browser with no server needed. All data is stored in browser localStorage. Perfect for:\n\n- Air-gapped environments\n- Quick demos without server setup\n- Offline usage\n- Distribution to users without technical setup\n\n**Note**: The offline version has limited backend features but provides full diagram editing, export/import, and localStorage persistence.\n\n## 📁 Project Structure\n\n```text\nToplogyBuilder/\n├── frontend/                  # Frontend application\n│   ├── src/\n│   │   ├── templates/        # Jinja2 templates\n│   │   │   ├── index.jinja   # Main template\n│   │   │   └── partials/     # Template components\n│   │   ├── index.html        # Generated HTML (from templates)\n│   │   ├── js/               # JavaScript modules\n│   │   │   ├── app.js        # Application entry point\n│   │   │   ├── canvas/       # Canvas event handlers\n│   │   │   ├── config/       # Configuration and constants\n│   │   │   ├── connections/  # Connection management\n│   │   │   ├── services/     # Storage and restore services\n│   │   │   ├── shapes/       # Shape factory and events\n│   │   │   ├── state/        # Application state\n│   │   │   ├── topology/     # File operations\n│   │   │   ├── ui/           # UI components and overlays\n│   │   │   └── utils/        # Utility functions\n│   │   └── styles/           # SCSS styles\n│   ├── dist/                 # Production build output\n│   ├── build-template.js     # Template rendering script\n│   └── package.json          # Frontend dependencies\n├── backend/                   # FastAPI backend\n│   ├── main.py               # API entry point\n│   └── requirements.txt      # Python dependencies\n├── docs/                      # Documentation\n│   ├── FRONTEND_ARCHITECTURE.md  # Frontend architecture guide\n│   ├── VSCODE_SETUP.md       # VS Code setup guide\n│   └── PRE_COMMIT_SETUP.md   # Pre-commit hooks guide\n├── .vscode/                   # VS Code configuration\n│   ├── settings.json         # Editor settings\n│   └── extensions.json       # Recommended extensions\n├── .pre-commit-config.yaml   # Pre-commit hooks configuration\n├── CHANGELOG.md              # Version history\n├── LICENSE                   # MIT License\n├── README.md                 # This file\n└── pyproject.toml            # Poetry configuration\n```\n\n## 🎮 Usage\n\n### Creating Shapes\n\n1. Click any shape button in the left sidebar\n2. Click on the canvas to place the shape\n3. Use the interaction circle to:\n   - **Left half**: Edit label and styling\n   - **Right half**: Create connection from this shape\n4. Drag shapes to reposition them (labels move automatically)\n5. Delete shapes with `Delete` or `Backspace` key\n\n### Editing Shape Labels\n\n1. Select a shape (click on it)\n2. Click the edit icon (left half of interaction circle)\n3. In the Shape Label panel, customize:\n   - **Label Text**: Enter text to display\n   - **Label Position**: Choose above, below, left, right, or center\n   - **Font Size**: Adjust text size\n   - **Label Color**: Pick text color\n4. Labels automatically stay attached during shape movement\n\n### Creating Connections\n\n1. Click the \"Add Connection\" button\n2. Click the source shape\n3. Click the target shape\n4. Connection appears with source and target labels\n\n### Editing Labels\n\n- **Shape Labels**: Click the edit icon in the interaction circle or select the shape\n- **Connection Labels**: Click the connection to open the Connection Details modal\n- **Dragging Labels**: Click and drag connection labels along their constraint circle\n\n### Managing Topology\n\n- **Save**: Automatically saved to browser localStorage\n- **Export**: Click \"Export Topology\" to download as JSON\n- **Import**: Click \"Import Topology\" to load from JSON file\n- **Clear**: Click \"Clear Topology\" to start fresh (after confirmation)\n\n### Zoom and Pan\n\n- **Zoom**: Use the zoom controls in the toolbar (25% to 400%)\n- **Pan**: Click and drag on empty canvas space\n- **Scroll**: Use mouse wheel or trackpad to scroll\n\n## 🔧 API Endpoints\n\n### Backend API\n\n- `GET /` - Root endpoint\n- `GET /api/health` - Health check endpoint\n- `GET /api/nodes` - Get all nodes\n- `POST /api/nodes` - Create a new node\n\n_Note: The current frontend uses localStorage for persistence. API integration is available for future enhancements._\n\n## 🛠️ Development\n\n### Code Formatting\n\nThis project uses automatic code formatting:\n\n- **Python**: Black formatter\n- **JavaScript/HTML/CSS**: Prettier\n- **Markdown**: markdownlint\n\nSee [docs/VSCODE_SETUP.md](docs/VSCODE_SETUP.md) for VS Code configuration.\n\n### Pre-commit Hooks\n\nRun before each commit to ensure code quality:\n\n```bash\n# Install pre-commit hooks\npoetry run pre-commit install\n\n# Run manually\npoetry run pre-commit run --all-files\n```\n\n### Project Scripts\n\n```bash\n# Start frontend development server\n./start-frontend.sh\n\n# Start backend server\n./start-backend.sh\n\n# Run both simultaneously (in separate terminals)\n```\n\n## 🏗️ Architecture\n\n### Frontend\n\n- **Modular Templates**: Jinja2 templates with reusable partials\n- **Build System**: Parcel bundler with asset optimization\n- **Styling**: SCSS with Bootstrap 5.3\n- **JavaScript**: ES6 modules with vanilla JavaScript\n- **State Management**: Centralized application state\n\n### Backend\n\n- **Framework**: FastAPI for REST APIs\n- **Static Files**: Serves frontend build from `/static/`\n- **CORS**: Configured for local development\n\n### Template Architecture\n\nThe frontend uses a modular Jinja2 template system:\n\n- **Templates**: Organized in `frontend/src/templates/`\n- **Partials**: Reusable components (navbar, sidebar, modals, etc.)\n- **Build Pipeline**: Templates → HTML → Parcel → Optimized Bundle\n- **Server Integration**: Backend serves the built static files\n\nSee [docs/FRONTEND_ARCHITECTURE.md](docs/FRONTEND_ARCHITECTURE.md) for detailed information.\n\n## 🔍 Troubleshooting\n\n### Labels Not Showing\n\nIf labels don't appear after adding them to shapes:\n\n1. Check browser console for errors\n2. Ensure the label text is not empty\n3. Try refreshing the page - labels are persisted in localStorage\n\n### Tooltips Not Appearing\n\nIf floating button tooltips don't work:\n\n1. Ensure Bootstrap 5.3 is loaded\n2. Try rebuilding templates: `cd frontend \u0026\u0026 npm run render`\n3. Check that `window.bootstrap` is available in browser console\n\n### Delete Key Not Working\n\n- On macOS, use `Backspace` key (labeled as Delete on keyboard)\n- On Windows/Linux, use `Delete` key\n- Ensure a shape is selected (should have blue outline)\n\n### Interaction Circle Issues\n\nIf the interaction circle appears multiple times or doesn't show:\n\n1. Refresh the page to clear any stale event listeners\n2. Ensure you're clicking on the shape itself, not its label\n3. Check that shape has proper `id` attribute\n\n### Pre-commit Hooks\n\nIf pre-commit hooks fail:\n\n```bash\n# Update hooks\npoetry run pre-commit autoupdate\n\n# Run manually to see detailed errors\npoetry run pre-commit run --all-files\n```\n\n## 🏗️ Building for Production\n\n### Full Build\n\n```bash\n# Build frontend and start integrated server\n./start-server.sh\n```\n\n### Frontend Build Only\n\n```bash\ncd frontend\nnpm run build\n```\n\nBuilt files will be in `frontend/dist/` with:\n\n- Optimized and minified HTML, CSS, JavaScript\n- Bundled dependencies\n- Hashed filenames for cache busting\n\n### Backend Deployment\n\nThe FastAPI backend can be deployed using:\n\n- **Uvicorn**: `uvicorn main:app --host 0.0.0.0 --port 8000`\n- **Docker**: Create a Dockerfile based on Python 3.10+\n- **Cloud Platforms**: AWS Lambda, Google Cloud Run, Azure Functions\n\nEnsure the `frontend/dist/` directory is deployed alongside the backend.\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\nPlease ensure:\n\n- Code is properly formatted (pre-commit hooks will help)\n- All tests pass\n- Documentation is updated if needed\n\n## 📝 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- Bootstrap 5.3 for UI components\n- Cisco network device icons for topology visualization\n- FastAPI for the backend framework\n\n## 📞 Support\n\nFor issues, questions, or contributions, please open an issue on GitHub.\n\n---\n\n**Built with ❤️ using Vanilla JavaScript, SASS, and FastAPI**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbvandewe%2Ftopolizer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbvandewe%2Ftopolizer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbvandewe%2Ftopolizer/lists"}