This commit is contained in:
122
docs/rack-planner/architecture.md
Normal file
122
docs/rack-planner/architecture.md
Normal file
@@ -0,0 +1,122 @@
|
||||
# System Architecture
|
||||
|
||||
## Overview
|
||||
|
||||
The system should be built as a web platform with a thin, responsive client and a server-side core for persistence, catalog management, plugin validation, and export generation.
|
||||
|
||||
## Main building blocks
|
||||
|
||||
### Frontend
|
||||
|
||||
- browser-based single-page application
|
||||
- visual rack editor
|
||||
- component library browser
|
||||
- BOM and cable views
|
||||
- import/export screens
|
||||
|
||||
### Backend API
|
||||
|
||||
- project CRUD
|
||||
- component catalog API
|
||||
- plugin upload and validation
|
||||
- bill of materials generation
|
||||
- cable estimation service
|
||||
- authentication and authorization
|
||||
|
||||
### Database
|
||||
|
||||
- users
|
||||
- projects
|
||||
- rack definitions
|
||||
- component instances
|
||||
- cable links
|
||||
- plugin manifests
|
||||
- catalog components
|
||||
|
||||
### Asset storage
|
||||
|
||||
- component `SVG` files
|
||||
- optional `glTF` assets
|
||||
- import files
|
||||
- generated exports such as `CSV` and `PDF`
|
||||
|
||||
## Recommended domain model split
|
||||
|
||||
### Planning domain
|
||||
|
||||
- racks
|
||||
- placements
|
||||
- connections
|
||||
- validation rules
|
||||
|
||||
### Catalog domain
|
||||
|
||||
- components
|
||||
- manufacturers
|
||||
- plugin packs
|
||||
- pricing metadata
|
||||
|
||||
### Output domain
|
||||
|
||||
- BOM
|
||||
- exports
|
||||
- printable documentation
|
||||
|
||||
## Rendering approach
|
||||
|
||||
For V1, prefer a 2D editor based on `SVG`.
|
||||
|
||||
Reasons:
|
||||
|
||||
- precise snap and measurement handling
|
||||
- easier labeling and overlays
|
||||
- simpler hit-testing for drag and resize interactions
|
||||
- lower implementation cost than a full 3D editor
|
||||
|
||||
3D can be added later as a secondary visualization layer using `glTF` assets and `Three.js`.
|
||||
|
||||
## Plugin ingestion approach
|
||||
|
||||
Do not load arbitrary CAD files directly into the editor runtime.
|
||||
|
||||
Use a controlled import pipeline:
|
||||
|
||||
1. user uploads a plugin package
|
||||
2. backend validates manifest and metadata
|
||||
3. backend validates assets and dimensions
|
||||
4. optional CAD conversion creates internal preview assets
|
||||
5. approved components become available in the catalog
|
||||
|
||||
This keeps the editor stable and the plugin model secure.
|
||||
|
||||
## Deployment model
|
||||
|
||||
### Public SaaS mode
|
||||
|
||||
- hosted centrally
|
||||
- user accounts and teams
|
||||
- shared component packs
|
||||
- subscription or usage-based pricing possible later
|
||||
|
||||
### Self-hosted mode
|
||||
|
||||
- optional future enterprise offering
|
||||
- internal catalogs
|
||||
- private component packs
|
||||
|
||||
## Security considerations
|
||||
|
||||
- signed or verified plugin packs if third-party distribution is allowed
|
||||
- strict asset and file-type validation
|
||||
- no execution of untrusted code in plugins
|
||||
- server-side permission checks for project access
|
||||
- rate limits on public endpoints
|
||||
|
||||
## Scaling considerations
|
||||
|
||||
- stateless API instances
|
||||
- database-backed persistence
|
||||
- object storage for assets
|
||||
- asynchronous jobs for heavy imports and exports
|
||||
|
||||
This is enough for an internet-facing product without overengineering the first release.
|
||||
113
docs/rack-planner/cable-length.md
Normal file
113
docs/rack-planner/cable-length.md
Normal file
@@ -0,0 +1,113 @@
|
||||
# Cable Length Calculation
|
||||
|
||||
## Goal
|
||||
|
||||
Estimate practical cable lengths from the physical arrangement of devices in a rack so users can preselect realistic patch and power cable variants.
|
||||
|
||||
The result should support planning, not exact installation certification.
|
||||
|
||||
## Use cases
|
||||
|
||||
- patch cable length between patch panel and switch
|
||||
- DAC or fiber estimate between devices in the same rack
|
||||
- power cable estimate from PDU to active device
|
||||
- BOM generation for preconfigured cable sets
|
||||
|
||||
## V1 approach
|
||||
|
||||
Cable length should be estimated from:
|
||||
|
||||
- rack unit position of both components
|
||||
- side of connection: front or rear
|
||||
- optional port offsets
|
||||
- route style
|
||||
- slack factor
|
||||
|
||||
## Suggested routing model
|
||||
|
||||
For V1, use a rule-based path estimate instead of full geometric routing.
|
||||
|
||||
### Inputs
|
||||
|
||||
- source component `U` position
|
||||
- target component `U` position
|
||||
- source and target side
|
||||
- rack depth
|
||||
- routing preference
|
||||
- slack percentage or fixed reserve
|
||||
|
||||
### Routing preferences
|
||||
|
||||
- `front_vertical`
|
||||
- `rear_vertical`
|
||||
- `front_to_rear`
|
||||
- `shortest_practical`
|
||||
|
||||
## Example calculation logic
|
||||
|
||||
Estimate length as:
|
||||
|
||||
1. vertical distance between source and target mounting positions
|
||||
2. plus horizontal or side transition allowance
|
||||
3. plus front/rear traversal allowance
|
||||
4. plus slack reserve
|
||||
|
||||
Illustrative formula:
|
||||
|
||||
```text
|
||||
estimated_length =
|
||||
vertical_distance_mm
|
||||
+ side_transition_mm
|
||||
+ front_rear_allowance_mm
|
||||
+ service_loop_mm
|
||||
```
|
||||
|
||||
Then round up to the next marketable cable length, for example:
|
||||
|
||||
- `0.25 m`
|
||||
- `0.5 m`
|
||||
- `1.0 m`
|
||||
- `1.5 m`
|
||||
- `2.0 m`
|
||||
- `3.0 m`
|
||||
|
||||
## Accuracy strategy
|
||||
|
||||
The tool should display:
|
||||
|
||||
- raw estimated length
|
||||
- recommended order length
|
||||
- confidence note such as `estimate only`
|
||||
|
||||
## Data requirements
|
||||
|
||||
Better cable estimation becomes possible if components expose ports with offsets.
|
||||
|
||||
Minimum V1:
|
||||
|
||||
- component `U` position only
|
||||
|
||||
Better V1:
|
||||
|
||||
- per-port offsets in the component metadata
|
||||
|
||||
## BOM integration
|
||||
|
||||
Cable entries can be generated as:
|
||||
|
||||
- one line per connection
|
||||
- or aggregated by cable type and recommended order length
|
||||
|
||||
Example:
|
||||
|
||||
- `12 x RJ45 patch cable Cat6A, 0.5 m`
|
||||
- `4 x C13 to C14 power cable, 1.5 m`
|
||||
|
||||
## Future improvements
|
||||
|
||||
- front and rear cable manager objects
|
||||
- reserved routing channels
|
||||
- left/right side path selection
|
||||
- bend radius constraints
|
||||
- color-coded cable groups
|
||||
- cross-rack cable planning
|
||||
139
docs/rack-planner/data-model.md
Normal file
139
docs/rack-planner/data-model.md
Normal file
@@ -0,0 +1,139 @@
|
||||
# Data Model
|
||||
|
||||
## Design principles
|
||||
|
||||
- components are metadata-driven
|
||||
- placement data is separate from catalog data
|
||||
- plugin-imported components must behave like built-in components
|
||||
- cable links are first-class entities
|
||||
|
||||
## Core entities
|
||||
|
||||
### RackTemplate
|
||||
|
||||
Describes a rack type that can be instantiated in projects.
|
||||
|
||||
Suggested fields:
|
||||
|
||||
- `id`
|
||||
- `name`
|
||||
- `rack_standard` as `10_inch` or `19_inch`
|
||||
- `total_u`
|
||||
- `usable_depth_mm`
|
||||
- `max_weight_kg`
|
||||
- `mounting_style`
|
||||
|
||||
### Project
|
||||
|
||||
- `id`
|
||||
- `name`
|
||||
- `owner_id`
|
||||
- `created_at`
|
||||
- `updated_at`
|
||||
- `status`
|
||||
|
||||
### RackInstance
|
||||
|
||||
- `id`
|
||||
- `project_id`
|
||||
- `rack_template_id`
|
||||
- `label`
|
||||
- `position_index`
|
||||
|
||||
### ComponentDefinition
|
||||
|
||||
Catalog entry for a reusable part.
|
||||
|
||||
- `id`
|
||||
- `source_type` as `builtin` or `plugin`
|
||||
- `plugin_id`
|
||||
- `manufacturer`
|
||||
- `part_number`
|
||||
- `name`
|
||||
- `category`
|
||||
- `rack_standard`
|
||||
- `height_u`
|
||||
- `width_mm`
|
||||
- `depth_mm`
|
||||
- `weight_kg`
|
||||
- `power_w`
|
||||
- `price_net`
|
||||
- `currency`
|
||||
- `front_svg_asset_id`
|
||||
- `preview_3d_asset_id`
|
||||
|
||||
### ComponentInstance
|
||||
|
||||
Placed component inside a rack.
|
||||
|
||||
- `id`
|
||||
- `project_id`
|
||||
- `rack_instance_id`
|
||||
- `component_definition_id`
|
||||
- `start_u`
|
||||
- `orientation`
|
||||
- `notes`
|
||||
|
||||
### PortDefinition
|
||||
|
||||
Optional port model for cable planning.
|
||||
|
||||
- `id`
|
||||
- `component_definition_id`
|
||||
- `name`
|
||||
- `side` as `front` or `rear`
|
||||
- `offset_x_mm`
|
||||
- `offset_y_mm`
|
||||
- `offset_z_mm`
|
||||
- `port_type`
|
||||
|
||||
### CableLink
|
||||
|
||||
- `id`
|
||||
- `project_id`
|
||||
- `from_component_instance_id`
|
||||
- `from_port_definition_id`
|
||||
- `to_component_instance_id`
|
||||
- `to_port_definition_id`
|
||||
- `cable_type`
|
||||
- `estimated_length_mm`
|
||||
- `slack_percent`
|
||||
- `manual_override_length_mm`
|
||||
|
||||
### PluginPack
|
||||
|
||||
- `id`
|
||||
- `name`
|
||||
- `version`
|
||||
- `vendor`
|
||||
- `manifest_version`
|
||||
- `status`
|
||||
- `imported_at`
|
||||
|
||||
## Validation rules
|
||||
|
||||
- `ComponentDefinition.rack_standard` must match `RackTemplate.rack_standard`
|
||||
- `ComponentInstance.start_u` plus `height_u` must not exceed rack height
|
||||
- placed components must not overlap
|
||||
- cable links should only reference valid ports belonging to the selected components
|
||||
|
||||
## BOM generation logic
|
||||
|
||||
The BOM should aggregate by:
|
||||
|
||||
- `manufacturer`
|
||||
- `part_number`
|
||||
- optional variant attributes such as color or length
|
||||
|
||||
The BOM should be able to combine:
|
||||
|
||||
- placed components
|
||||
- accessory parts
|
||||
- calculated cables
|
||||
|
||||
## Future extensions
|
||||
|
||||
- multi-rack room coordinates
|
||||
- thermal zones
|
||||
- separate front and rear accessories
|
||||
- stock and supplier integration
|
||||
79
docs/rack-planner/mvp.md
Normal file
79
docs/rack-planner/mvp.md
Normal file
@@ -0,0 +1,79 @@
|
||||
# MVP Scope
|
||||
|
||||
## Objective
|
||||
|
||||
Release a public web application that solves the core planning workflow for `10"` and `19"` racks without waiting for full CAD-grade capabilities.
|
||||
|
||||
## MVP features
|
||||
|
||||
### 1. Rack editor
|
||||
|
||||
- create a rack project
|
||||
- choose rack type: `10"` or `19"`
|
||||
- define rack height in `U`
|
||||
- define depth and optional width variant
|
||||
- front view editor with occupied `U` grid
|
||||
- drag-and-drop placement of components
|
||||
- move and reorder components
|
||||
- remove and duplicate components
|
||||
|
||||
### 2. Component library
|
||||
|
||||
- built-in catalog with common rack elements
|
||||
- categories such as patch panel, switch, server, PDU, shelf, UPS, blank panel
|
||||
- searchable component picker
|
||||
- component detail panel with dimensions and metadata
|
||||
|
||||
### 3. Validation
|
||||
|
||||
- enforce rack width compatibility
|
||||
- enforce `U` occupancy
|
||||
- warn on depth overflow
|
||||
- warn on weight limit overflow if rack limits are defined
|
||||
|
||||
### 4. Bill of materials
|
||||
|
||||
- aggregate identical parts
|
||||
- export as `CSV`
|
||||
- show quantity, part number, manufacturer, description, unit price, total price
|
||||
- optionally list accessories separately
|
||||
|
||||
### 5. Plugin support
|
||||
|
||||
- import component packs based on a defined manifest
|
||||
- metadata-driven components
|
||||
- 2D visuals via `SVG`
|
||||
- optional 3D visual asset reference for future use
|
||||
|
||||
### 6. Cable planning V1
|
||||
|
||||
- define cable links between two ports or two devices
|
||||
- estimate route length using rack positions
|
||||
- allow manual slack factor
|
||||
- include cables in bill of materials
|
||||
|
||||
## Deliberately excluded from MVP
|
||||
|
||||
- freeform 3D editing
|
||||
- native browser editing of `STEP` or `DXF`
|
||||
- multi-rack room layout
|
||||
- thermal simulation
|
||||
- live collaboration
|
||||
- advanced permission and approval workflows
|
||||
- ERP integration
|
||||
|
||||
## Recommended MVP stack
|
||||
|
||||
- frontend: `React` + `TypeScript`
|
||||
- editor rendering: `SVG` or `Canvas` for 2D rack view
|
||||
- backend: `Node.js` or `PHP` API, depending on preferred team stack
|
||||
- database: `PostgreSQL`
|
||||
- storage: object storage for plugin assets and exports
|
||||
|
||||
## Success criteria
|
||||
|
||||
- a user can build a rack layout in under 10 minutes
|
||||
- the system prevents invalid `U` placement
|
||||
- the generated bill of materials is usable for procurement
|
||||
- plugin packs can be added without code changes in the editor
|
||||
- cable length estimates are close enough for practical preselection
|
||||
138
docs/rack-planner/plugin-spec.md
Normal file
138
docs/rack-planner/plugin-spec.md
Normal file
@@ -0,0 +1,138 @@
|
||||
# Plugin Specification
|
||||
|
||||
## Goal
|
||||
|
||||
The plugin system should allow additional rack components to be imported without changing application code.
|
||||
|
||||
Plugins should be data packages, not executable extensions.
|
||||
|
||||
## Principles
|
||||
|
||||
- no arbitrary code execution
|
||||
- manifest-based validation
|
||||
- stable schema versioning
|
||||
- internal conversion of optional CAD-derived assets
|
||||
|
||||
## Package structure
|
||||
|
||||
Example:
|
||||
|
||||
```text
|
||||
vendor-pack-1/
|
||||
manifest.json
|
||||
components/
|
||||
switch-24p.json
|
||||
patchpanel-24p.json
|
||||
assets/
|
||||
front/
|
||||
switch-24p.svg
|
||||
patchpanel-24p.svg
|
||||
preview3d/
|
||||
switch-24p.gltf
|
||||
```
|
||||
|
||||
## Manifest example
|
||||
|
||||
```json
|
||||
{
|
||||
"manifestVersion": 1,
|
||||
"name": "Example Network Pack",
|
||||
"vendor": "Example Vendor",
|
||||
"version": "1.0.0",
|
||||
"components": [
|
||||
"components/switch-24p.json",
|
||||
"components/patchpanel-24p.json"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Component definition example
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "24-Port Patch Panel",
|
||||
"manufacturer": "Example Vendor",
|
||||
"partNumber": "PP-24-1U",
|
||||
"category": "patch_panel",
|
||||
"rackStandard": "19_inch",
|
||||
"heightU": 1,
|
||||
"depthMm": 95,
|
||||
"weightKg": 1.2,
|
||||
"priceNet": 79.0,
|
||||
"currency": "EUR",
|
||||
"assets": {
|
||||
"frontSvg": "assets/front/patchpanel-24p.svg"
|
||||
},
|
||||
"ports": [
|
||||
{
|
||||
"name": "Port 1",
|
||||
"side": "front",
|
||||
"offsetXmm": 18,
|
||||
"offsetYmm": 10,
|
||||
"offsetZmm": 0,
|
||||
"portType": "rj45"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Supported file formats
|
||||
|
||||
### V1 mandatory
|
||||
|
||||
- `JSON` for manifest and component metadata
|
||||
- `SVG` for 2D visuals
|
||||
|
||||
### V1 optional
|
||||
|
||||
- `glTF` for future 3D preview assets
|
||||
|
||||
### Later import formats
|
||||
|
||||
These should be handled through an import pipeline, not as runtime-native editor formats:
|
||||
|
||||
- `DXF`
|
||||
- `STEP`
|
||||
- `OBJ`
|
||||
|
||||
## Validation rules
|
||||
|
||||
- schema version must be supported
|
||||
- required metadata fields must exist
|
||||
- asset references must resolve inside the package
|
||||
- all dimensions must be plausible and positive
|
||||
- category values must match allowed enums
|
||||
- unsupported formats are rejected or ignored
|
||||
|
||||
## Security model
|
||||
|
||||
Plugins must never contain executable JavaScript for the editor.
|
||||
|
||||
Allowed plugin content:
|
||||
|
||||
- metadata
|
||||
- images
|
||||
- vector graphics
|
||||
- optional validated model assets
|
||||
|
||||
Rejected:
|
||||
|
||||
- scripts
|
||||
- external network callbacks
|
||||
- embedded active content
|
||||
|
||||
## Import workflow
|
||||
|
||||
1. upload package
|
||||
2. unpack in isolated temporary storage
|
||||
3. validate manifest
|
||||
4. validate component schema
|
||||
5. validate assets
|
||||
6. register catalog entries
|
||||
7. make components available to selected users or globally
|
||||
|
||||
## Versioning strategy
|
||||
|
||||
- application schema versioning is independent from plugin pack version
|
||||
- manifest schema must be explicitly versioned
|
||||
- deprecated fields should have a migration path where possible
|
||||
71
docs/rack-planner/product-concept.md
Normal file
71
docs/rack-planner/product-concept.md
Normal file
@@ -0,0 +1,71 @@
|
||||
# Product Concept
|
||||
|
||||
## Problem
|
||||
|
||||
There is no widely available, lightweight online tool focused on practical planning of `10"` and `19"` racks with a visual workflow, reusable components, and a usable bill of materials.
|
||||
|
||||
Existing workflows are often split across:
|
||||
|
||||
- CAD tools that are too heavy for simple planning
|
||||
- spreadsheets for the bill of materials
|
||||
- manual sketches for positioning
|
||||
- separate notes for cabling
|
||||
|
||||
## Vision
|
||||
|
||||
`code.it Rack Planner` should be a browser-based planning platform where users can:
|
||||
|
||||
- create and save rack layouts online
|
||||
- visually place and move rack components
|
||||
- load manufacturer-specific or custom components as plugins
|
||||
- generate a bill of materials automatically
|
||||
- estimate cable lengths between ports or devices
|
||||
|
||||
## Target users
|
||||
|
||||
- system integrators
|
||||
- installers
|
||||
- IT administrators
|
||||
- AV and media technicians
|
||||
- control cabinet / small infrastructure planners
|
||||
- organizations documenting existing rack installations
|
||||
|
||||
## Primary use cases
|
||||
|
||||
1. Plan a new `19"` network rack with switch, patch panel, PDU, UPS, shelves, and servers.
|
||||
2. Plan a compact `10"` wall rack for small office or edge installations.
|
||||
3. Compare multiple rack variants with different hardware selections.
|
||||
4. Export a bill of materials for ordering.
|
||||
5. Estimate patch cable and power cable lengths based on mounting positions.
|
||||
|
||||
## Functional goals
|
||||
|
||||
- visual rack editor
|
||||
- component catalog
|
||||
- drag-and-drop placement
|
||||
- snap-to-unit positioning
|
||||
- collision and fit validation
|
||||
- bill of materials generation
|
||||
- import of additional component packs
|
||||
- optional cable planning and length estimation
|
||||
|
||||
## Non-functional goals
|
||||
|
||||
- runs in a modern browser
|
||||
- usable on desktop first, tablet second
|
||||
- clean project persistence
|
||||
- suitable for public internet deployment
|
||||
- secure plugin loading model
|
||||
- scalable enough for many concurrent users
|
||||
|
||||
## Scope boundary
|
||||
|
||||
The product should not try to replace full mechanical CAD in the first versions. The planning focus is:
|
||||
|
||||
- layout
|
||||
- occupancy
|
||||
- compatibility
|
||||
- documentation
|
||||
- ordering support
|
||||
|
||||
Mechanical precision modeling, freeform CAD editing, and simulation should remain outside the initial scope.
|
||||
56
docs/rack-planner/roadmap.md
Normal file
56
docs/rack-planner/roadmap.md
Normal file
@@ -0,0 +1,56 @@
|
||||
# Roadmap
|
||||
|
||||
## Phase 0: Product foundation
|
||||
|
||||
- finalize terminology and target market
|
||||
- define core rack and component schemas
|
||||
- prepare UX wireframes for the editor
|
||||
- prepare initial built-in component catalog
|
||||
|
||||
## Phase 1: MVP
|
||||
|
||||
- project creation
|
||||
- rack editor for `10"` and `19"`
|
||||
- drag-and-drop placement
|
||||
- `U` grid and collision checks
|
||||
- built-in catalog
|
||||
- BOM export as `CSV`
|
||||
- plugin pack import with `JSON` plus `SVG`
|
||||
- simple cable estimation
|
||||
|
||||
## Phase 2: Public beta
|
||||
|
||||
- user accounts
|
||||
- project persistence
|
||||
- shareable project links
|
||||
- improved BOM formatting
|
||||
- printable rack reports
|
||||
- better plugin management UI
|
||||
|
||||
## Phase 3: Professional planning
|
||||
|
||||
- 3D preview
|
||||
- manufacturer packs
|
||||
- advanced validation rules
|
||||
- richer cable routing logic
|
||||
- multi-rack projects
|
||||
- PDF export packages
|
||||
|
||||
## Phase 4: Commercial maturity
|
||||
|
||||
- team workspaces
|
||||
- access control
|
||||
- audit log
|
||||
- supplier and ERP exports
|
||||
- private catalogs
|
||||
- self-hosted deployment option
|
||||
|
||||
## Product recommendation
|
||||
|
||||
The strongest path is:
|
||||
|
||||
1. ship a narrow and useful browser editor first
|
||||
2. prove demand with real planners and installers
|
||||
3. expand catalogs, exports, and collaboration after usage feedback
|
||||
|
||||
The public internet goal is realistic, but only if V1 stays disciplined and does not start as a generalized CAD platform.
|
||||
Reference in New Issue
Block a user