307 lines
9.5 KiB
Markdown
307 lines
9.5 KiB
Markdown
# Datacenter Designer
|
||
|
||
A lightweight web application for visual design of datacenter infrastructure. Plan rack layouts, place devices, and map network connections with an intuitive drag-and-drop interface.
|
||
|
||
|
||
|
||
|
||
|
||
## Features
|
||
|
||
- **Visual Rack Layout**: Drag-and-drop racks on an infinite canvas
|
||
- **Device Management**: Place network devices in rack slots (U1-U42) with multi-unit form factors
|
||
- **Network Connections**: Map port-to-port connections between devices
|
||
- **Dual Views**: Physical (rack-based) and logical (topology) views
|
||
- **Project Management**: Organize multiple datacenter designs
|
||
- **Table Views**: Spreadsheet-style editing with ag-Grid integration
|
||
- **Export/Import**: Save projects as JSON or export tables to Excel (.xlsx)
|
||
- **Zero Configuration**: SQLite database, no setup required
|
||
|
||
## Quick Start
|
||
|
||
### Prerequisites
|
||
|
||
- Node.js 14.0 or higher
|
||
- npm (comes with Node.js)
|
||
|
||
### Installation
|
||
|
||
```bash
|
||
# Clone the repository
|
||
git clone https://github.com/yourusername/datacenter-designer.git
|
||
cd datacenter-designer
|
||
|
||
# Install dependencies
|
||
npm install
|
||
|
||
# Start the server
|
||
npm start
|
||
```
|
||
|
||
The application will be available at **http://localhost:3000**
|
||
|
||
## Usage Guide
|
||
|
||
### Creating Racks
|
||
|
||
1. Right-click on empty canvas → "Add Rack(s)"
|
||
2. Configure the modal:
|
||
- **Number of racks**: Create 1-20 racks at once
|
||
- **Name prefix**: Custom naming prefix (default: RACK)
|
||
- **Position**: Continue current row, new row below, or new row above
|
||
3. Click "Create" - racks will be generated with sequential numbering (RACK01, RACK02, etc.)
|
||
|
||
### Adding Devices
|
||
|
||
1. Right-click inside a rack → Select device type from modal
|
||
2. Enter device name
|
||
3. Device is placed in the next available slot
|
||
4. Supports multi-unit form factors (1U to 42U)
|
||
|
||
### Creating Connections
|
||
|
||
1. Right-click on source device → "Create Connection"
|
||
2. Select source port (used ports are grayed out)
|
||
3. Click on target device
|
||
4. Select target port
|
||
5. Connection line is drawn automatically
|
||
|
||
**Managing Connection Waypoints:**
|
||
- **Add waypoint**: Double-click on the connection line
|
||
- **Move waypoint**: Drag the waypoint handle to reposition
|
||
- **Delete waypoint**: Double-click on a waypoint handle
|
||
- **Note**: Edge connection points (at devices) cannot be deleted
|
||
|
||
### Navigation
|
||
|
||
- **Zoom**: `Ctrl` + Mouse Wheel
|
||
- **Pan**: Click and drag on empty canvas
|
||
- **Lock/Unlock Racks**: Right-click on rack → Toggle lock (prevents accidental movement)
|
||
- **Delete**: Right-click on item → "Delete", or select connection and press `Delete` key
|
||
|
||
### Views
|
||
|
||
- **Physical View**: Shows devices arranged in racks (default)
|
||
- **Logical View**: Shows network topology without rack constraints
|
||
- **Table Views**: Toggle Racks, Devices, or Connections table for spreadsheet-style editing
|
||
|
||
### Export/Import
|
||
|
||
- **Export Project**: Saves complete project as JSON (includes all racks, devices, connections, and settings)
|
||
- **Import Project**: Load a previously exported project (creates new project with " (Imported)" suffix)
|
||
- **Export to Excel**: Downloads .xlsx file with 3 sheets: Racks, Devices, Connections
|
||
|
||
## Technology Stack
|
||
|
||
| Layer | Technology | Purpose |
|
||
|-------|-----------|---------|
|
||
| **Frontend** | Vanilla JavaScript (ES6 modules) | No build process, direct browser execution |
|
||
| | Konva.js | HTML5 Canvas library for visual elements |
|
||
| | ag-Grid | Spreadsheet-style table component |
|
||
| | SheetJS | Excel export functionality |
|
||
| **Backend** | Node.js + Express | RESTful API server with modular routes |
|
||
| **Database** | better-sqlite3 | Synchronous SQLite, 2-3x faster than async |
|
||
|
||
## Project Structure
|
||
|
||
```
|
||
datacenter-designer/
|
||
├── server/ # Backend
|
||
│ ├── config.js # Configuration constants
|
||
│ ├── server.js # Express application setup
|
||
│ ├── db.js # Database operations (better-sqlite3)
|
||
│ ├── routes/ # Modular API routes
|
||
│ │ ├── projects.js
|
||
│ │ ├── racks.js
|
||
│ │ ├── devices.js
|
||
│ │ └── connections.js
|
||
│ └── lib/
|
||
│ └── errorHandler.js # Centralized error handling
|
||
├── public/ # Frontend (served statically)
|
||
│ ├── index.html # Main HTML file
|
||
│ ├── css/
|
||
│ │ ├── config.css # CSS variables and theming
|
||
│ │ └── style.css # Component styles
|
||
│ └── js/
|
||
│ ├── config.js # Frontend configuration
|
||
│ ├── app.js # Main application controller
|
||
│ ├── lib/ # Shared utilities
|
||
│ │ ├── api.js # API client
|
||
│ │ └── ui.js # UI utilities (Toast, Modal, etc.)
|
||
│ └── managers/ # Feature modules
|
||
│ ├── rack-manager.js # Rack rendering and interaction
|
||
│ ├── device-manager.js # Device rendering and interaction
|
||
│ ├── connection-manager.js # Connection lines and waypoints
|
||
│ └── table-manager.js # Table view management
|
||
├── database/ # SQLite database (auto-created)
|
||
│ └── datacenter.db
|
||
└── package.json
|
||
```
|
||
|
||
## Configuration
|
||
|
||
The application uses sensible defaults and requires no configuration. Key parameters:
|
||
|
||
- **Port**: 3000 (change via `PORT` environment variable)
|
||
- **Database**: `database/datacenter.db` (auto-created on first run)
|
||
- **Rack Dimensions**: 520px × 1485px (42U standard)
|
||
- **Grid Spacing**: 600px horizontal, 1585px vertical
|
||
|
||
## Database Schema
|
||
|
||
### Core Tables
|
||
|
||
- **projects**: Isolated workspaces
|
||
- **racks**: Physical rack cabinets with positions
|
||
- **device_types**: Library of available device types (switches, routers, etc.)
|
||
- **devices**: Device instances placed in racks
|
||
- **connections**: Port-to-port network connections
|
||
|
||
### Key Relationships
|
||
|
||
- Projects → Racks (one-to-many)
|
||
- Racks → Devices (one-to-many)
|
||
- Devices → Connections (many-to-many via source/target)
|
||
|
||
## Keyboard Shortcuts
|
||
|
||
| Key | Action |
|
||
|-----|--------|
|
||
| `Ctrl + Wheel` | Zoom in/out |
|
||
| `Esc` | Cancel connection mode / Deselect |
|
||
| `Delete` / `Backspace` | Delete selected connection |
|
||
|
||
## Browser Support
|
||
|
||
- ✅ Chrome 90+ (recommended)
|
||
- ✅ Firefox 88+
|
||
- ✅ Safari 14+
|
||
- ✅ Edge 90+
|
||
|
||
## Development
|
||
|
||
### Running in Development Mode
|
||
|
||
```bash
|
||
npm start
|
||
# or
|
||
npm run dev
|
||
```
|
||
|
||
Both commands start the same server on port 3000. The application uses ES6 modules directly, so no build process is needed.
|
||
|
||
### Project Principles
|
||
|
||
This project follows KISS, DRY, and SOLID principles:
|
||
|
||
- **Simple tech stack**: No build tools, no heavy frameworks
|
||
- **Modular design**: Separate managers for racks, devices, connections, and tables
|
||
- **RESTful API**: Clean separation between frontend and backend
|
||
- **SQLite**: Lightweight, zero-config database perfect for this use case
|
||
|
||
For detailed technical documentation, see [CLAUDE.md](./CLAUDE.md).
|
||
|
||
## Troubleshooting
|
||
|
||
### Port Already in Use
|
||
|
||
```bash
|
||
# Linux/Mac
|
||
PORT=3001 npm start
|
||
|
||
# Windows
|
||
set PORT=3001 && npm start
|
||
```
|
||
|
||
### Database Locked Error
|
||
|
||
```bash
|
||
# Stop all running instances
|
||
pkill -f "node server/server.js"
|
||
|
||
# Delete lock files
|
||
rm database/*.db-shm database/*.db-wal
|
||
|
||
# Restart
|
||
npm start
|
||
```
|
||
|
||
### Canvas Not Rendering
|
||
|
||
- Clear browser cache and reload
|
||
- Check browser console for errors
|
||
- Ensure JavaScript is enabled
|
||
- Try a different browser
|
||
|
||
## Contributing
|
||
|
||
Contributions are welcome! Please follow these guidelines:
|
||
|
||
1. Fork the repository
|
||
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
|
||
3. Commit your changes (`git commit -m 'feat: add amazing feature'`)
|
||
4. Push to the branch (`git push origin feature/amazing-feature`)
|
||
5. Open a Pull Request
|
||
|
||
See [CLAUDE.md](./CLAUDE.md) for detailed development guidelines.
|
||
|
||
## Roadmap
|
||
|
||
### Phase 1: Core UX Improvements
|
||
- [ ] Undo/redo functionality
|
||
- [ ] Enhanced keyboard shortcuts
|
||
- [ ] Toast notifications (replace browser alerts)
|
||
- [ ] Search and filter
|
||
- [ ] Batch operations (select multiple items)
|
||
- [ ] Auto-save functionality
|
||
|
||
### Phase 2: Multi-User Support
|
||
- [ ] User management system
|
||
- [ ] Authentication and authorization
|
||
- [ ] OIDC-compatible external SSO integration
|
||
- [ ] Project sharing between users
|
||
- [ ] Role-based access control (view/edit/admin)
|
||
|
||
### Phase 3: Collaboration
|
||
- [ ] Real-time collaborative editing
|
||
- [ ] Concurrent access management
|
||
- [ ] User presence indicators
|
||
- [ ] Change notifications
|
||
- [ ] Conflict resolution
|
||
|
||
### Phase 4: Advanced Features
|
||
- [ ] Custom device types
|
||
- [ ] Cable labeling and management
|
||
- [ ] VLAN visualization
|
||
- [ ] IP address management
|
||
- [ ] Documentation generation
|
||
|
||
### Phase 5: Platform Enhancements
|
||
- [ ] Dark mode
|
||
- [ ] Mobile/tablet responsive design
|
||
- [ ] 3D rack visualization
|
||
- [ ] Enhanced export formats
|
||
- [ ] API for third-party integrations
|
||
|
||
## License
|
||
|
||
MIT License - feel free to use this project for any purpose.
|
||
|
||
## Acknowledgments
|
||
|
||
- [Konva.js](https://konvajs.org/) - HTML5 Canvas library
|
||
- [ag-Grid](https://www.ag-grid.com/) - Feature-rich data grid
|
||
- [SheetJS](https://sheetjs.com/) - Excel file generation
|
||
- [Express.js](https://expressjs.com/) - Web framework
|
||
- [SQLite](https://www.sqlite.org/) - Embedded database
|
||
|
||
## Support
|
||
|
||
- **Issues**: [GitHub Issues](https://github.com/yourusername/datacenter-designer/issues)
|
||
- **Discussions**: [GitHub Discussions](https://github.com/yourusername/datacenter-designer/discussions)
|
||
- **Documentation**: See [CLAUDE.md](./CLAUDE.md) for technical details
|
||
|
||
---
|
||
|
||
**Built with ❤️ and KISS principles**
|