Concepts¶

This page explains the core data model and how the different components of NetBox Pathways relate to each other.

Data Model Overview¶

erDiagram
    Structure ||--o{ Pathway : "start/end"
    Structure ||--o{ ConduitBank : contains
    Structure ||--o{ ConduitJunction : "towards"
    Pathway ||--o{ CableSegment : routes
    Pathway ||--|{ PathwayLocation : "passes through"
    Cable ||--o{ CableSegment : "routed via"
    ConduitBank ||--o{ Conduit : positions
    Conduit ||--o{ Innerduct : contains
    Conduit ||--o{ ConduitJunction : "branches at"
    Pathway <|-- Conduit : extends
    Pathway <|-- AerialSpan : extends
    Pathway <|-- DirectBuried : extends
    Pathway <|-- Innerduct : extends

Structures¶

A Structure is any physical location where cables can enter, exit, or transition between pathway types. Structures have geographic coordinates (Point or Polygon geometry) in their geometry field, and can be assigned to a NetBox Site and to a Location within that site.

Structures serve as endpoints for Pathways and anchor points for Conduit Banks.

A structure is a container. Equipment that lives inside one -- a splice closure, for instance -- is a dcim.Device assigned to the same site and location, not a structure in its own right.

Pathways¶

A Pathway is a physical route between two endpoints. It has a LineString geometry (the geographic path) and connects structures, locations, or junctions.

Pathways use multi-table inheritance with four subtypes:

Endpoint Flexibility¶

Pathways support flexible endpoints to model both outdoor and indoor infrastructure:

• Structure — A pole, manhole, or other physical structure
• Location — A NetBox dcim.Location (room, floor, wing)
• Junction — A conduit junction (Y-tee) for conduit subtypes only

Each pathway has exactly one start endpoint and one end endpoint. These can be different types (e.g., a conduit starting at a manhole and ending at a building location).

Conduit Banks¶

A Conduit Bank represents a group of conduit openings on one side of a structure — typically a wall in a manhole or handhole. Banks have a configuration (e.g., 2x3 for 2 rows by 3 columns) and track the total number of openings.

Individual Conduits are assigned to a bank with a Bank Position (e.g., A1, B2). Each position within a bank is unique.

Conduit Junctions¶

A Conduit Junction models a Y-tee where a branch conduit meets a trunk conduit at a point along its span. Key attributes:

• Trunk Conduit — The main conduit being tapped
• Branch Conduit — The conduit branching off
• Towards Structure — Which end of the trunk the junction faces
• Position on Trunk — Normalized position (0.0 to 1.0) along the trunk

The junction's geographic location is interpolated from the trunk conduit's path geometry.

Cable Segments¶

A Cable Segment links a NetBox dcim.Cable to a Pathway. Multiple segments trace a cable's complete physical route:

Cable segments ordered by sequence form a complete pull sheet for field crews.

Pathway Locations¶

A Pathway Location records intermediate waypoints along a pathway's route — locations the pathway passes through between its start and end. Each waypoint references a NetBox Site or Location and has a sequence number for ordering.

Site Geometry¶

A Site Geometry links a NetBox Site to the Pathways geospatial system. It can hold an explicit geometry or fall back to a linked Structure's location. This model enables external plugins to reference Site-based geometry through the Map Layer Registry.

Relationship to NetBox Core¶

NetBox Pathways integrates with several core NetBox models: