Metadata-Version: 2.4
Name: netbox-wdm
Version: 0.2.2
Summary: WDM wavelength management for NetBox - ITU channel plans, ROADM editing, and position stack enforcement
Author-email: Jonathan Senecal <contact@jonathansenecal.com>
License-Expression: AGPL-3.0-or-later
Project-URL: Homepage, https://github.com/jsenecal/netbox-wdm
Project-URL: Source, https://github.com/jsenecal/netbox-wdm
Project-URL: Changelog, https://github.com/jsenecal/netbox-wdm/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/jsenecal/netbox-wdm/issues
Project-URL: Documentation, https://jsenecal.github.io/netbox-wdm/
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: bumpver; extra == "dev"
Requires-Dist: pre-commit>=4.0.0; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-django>=4.5.0; extra == "dev"
Requires-Dist: pytest-cov>=3.0.0; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Provides-Extra: docs
Requires-Dist: zensical; extra == "docs"
Dynamic: license-file

# netbox-wdm

> A [NetBox](https://github.com/netbox-community/netbox) 4.5+ plugin for WDM (Wavelength Division Multiplexing) device management.

[![PyPI](https://img.shields.io/pypi/v/netbox-wdm.svg)](https://pypi.org/project/netbox-wdm/)
[![Python](https://img.shields.io/pypi/pyversions/netbox-wdm.svg)](https://pypi.org/project/netbox-wdm/)
[![NetBox](https://img.shields.io/badge/NetBox-4.5%2B-success.svg)](https://github.com/netbox-community/netbox)
[![CI](https://github.com/jsenecal/netbox-wdm/actions/workflows/ci.yml/badge.svg)](https://github.com/jsenecal/netbox-wdm/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/jsenecal/netbox-wdm/branch/main/graph/badge.svg)](https://codecov.io/gh/jsenecal/netbox-wdm)
![Status](https://img.shields.io/badge/status-alpha-orange)
[![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL%203.0-blue.svg)](LICENSE)

Manages ITU channel plans, channel-to-port assignments, trunk port identification, ROADM live editing, and wavelength service tracking.

> **Alpha software.** The API and data model may change between releases. Use in production at your own risk.

## Features

- **Overlay pattern** -- `WdmDeviceTypeProfile` overlays `DeviceType` (blueprint), `WdmNode` overlays `Device` (instance).
- **Dual port support** -- separate MUX and DEMUX front port assignments per channel, with duplex and single-fiber modes.
- **ITU grid support** -- DWDM 100 GHz (44 ch), DWDM 50 GHz (88 ch), CWDM (18 ch).
- **EXP / 1310 ports** -- express upgrade and 1310 nm gray optic pass-through as COM rear port positions.
- **Auto-population** -- channels automatically created from profile templates when a device is added.
- **DeviceType integration** -- WDM Profile tab on DeviceType detail pages.
- **Wavelength editor** -- TypeScript frontend with undo/redo, dirty state, optimistic concurrency, conditional MUX/DEMUX columns.
- **Wavelength services** -- end-to-end service tracking with sequenced channel assignments and PROTECT guards.
- **Circuit trace visualization** -- interactive horizontal flow diagram on `WdmCircuit` detail pages.
- **Full CRUD stack** -- list, detail, edit, delete, bulk import/edit/delete views for all models.
- **REST API** -- CRUD endpoints plus `apply-mapping` (atomic ROADM editor) and `stitch` (wavelength path).
- **GraphQL** -- strawberry-django types, filters, and schema for all models.
- **Sample data** -- management command with realistic WDM topologies, patch panels, and end-to-end cabling.

## Compatibility

| Plugin version | NetBox version | Python    |
|----------------|----------------|-----------|
| 0.2.x          | 4.5            | 3.12-3.14 |

## Installation

```bash
pip install netbox-wdm
```

In your NetBox `configuration.py`:

```python
PLUGINS = ["netbox_wdm"]
```

Apply migrations:

```bash
cd /opt/netbox/netbox
python manage.py migrate
```

## Documentation

Full documentation: **[jsenecal.github.io/netbox-wdm](https://jsenecal.github.io/netbox-wdm/)**

Key references:
- `docs/developer/architecture` -- overlay pattern, port topology, position-stack alignment.
- `docs/developer/style-guide` -- frontend conventions for the TypeScript components.

## Models

| Model | Description |
|-------|-------------|
| `WdmDeviceTypeProfile` | 1:1 overlay on `dcim.DeviceType` -- defines grid, node type, and fiber type (duplex / single-fiber) |
| `WdmChannelTemplate`   | Channel-to-port blueprint with MUX and DEMUX front port template assignments |
| `WdmNode`              | 1:1 overlay on `dcim.Device` -- instance of a WDM device |
| `WdmLinePort`          | Identifies trunk RearPorts with direction (common / east / west) and role (tx / rx / bidi) |
| `WdmChannel`           | Per-channel instance with MUX and DEMUX front port assignments |
| `WdmWavelengthPath`    | End-to-end traced path through the cable plant between WDM nodes |
| `WdmCircuit`           | Logical service grouping one or more wavelength paths |

## Contributing

PRs welcome. Use conventional-commits PR titles (`feat:`, `fix:`, `chore:`, `docs:`, ...) -- release-drafter assembles release notes from them. Run `make setup` after cloning to install dev dependencies and the pre-commit hooks (including the AI-attribution-rejecting `commit-msg` hook).

## License

[AGPL-3.0-or-later](LICENSE).
