FiberCAD — Final Project Report

1. Executive Summary

What FiberCAD is, what it does, and what the demo proves.

FiberCAD is a Python engine that takes a geographic bounding box and produces a complete fiber-to-the-home (FTTH) network design: boundary groups, splitter trees, conduit routing, equipment placement, compliance validation, DXF drawings, interactive HTML reports, and BOM workbooks.

Every output layer is cryptographically signed with Ed25519 and chained — a standalone verifier with zero FiberCAD dependencies can validate the entire provenance chain from input through compliance.

Demo Pipeline Result

Bounding Box

→

460 Buildings
36 Roads

→

14 Boundary Groups
70 Splitters

→

7,886 ft Conduit
35 Handholes

→

PASS
18 rules checked

Input: -79.835, 36.068, -79.825, 36.075 (Hampton Heights, Greensboro NC). Output: 6 artifacts including permit-ready DXF, interactive map, and 5-sheet BOM workbook.

2. System Architecture

Microkernel design with layered data architecture and tools-first LLM integration.

Module Map

fibercad/
  cli.py              CLI entry point — bbox to artifacts
  kernel/             Microkernel: config, project container, errors
  model/              Domain model: dataclasses for equipment, conduit, splitters
  ingest/             OSM/Overpass, CSV, GeoJSON, Shapefile import
  planning/
    boundary.py       Geographic clustering into boundary groups
    splitters.py      1x8 / 1x4 two-stage splitter hierarchy
    routing.py        MST conduit routing along road network
    optimizer.py      Pass-through elimination, conduit dedup
    fiber_assign.py   LLD strand assignment (tube/fiber colors)
    service.py        Full L0 → L4 orchestration pipeline
  rules/
    profiles/         Pluggable standards (Lumos V6, generic)
    client_rules.py   13 source-tagged rules with phase builders
    registry.py       Profile registration and lookup
  output/
    fiberjson.py      Layered schema + integrity signing
    dxf_writer.py     AutoCAD DXF with 33 real Lumos blocks
    html_report.py    Leaflet map with layer controls
    workbook.py       5-sheet BOM Excel workbook
    validation_report.py   Human-readable compliance report
  tools/              7 MCP-compatible baremetal tools
  llm/                Claude agent + multi-round QA
  verify/             Standalone integrity chain verifier
  assets/blocks/      33 DXF block definitions from Lumos template

Layered Data Architecture

Layer	Name	Content	Algorithm
L0	Input	Bounding box / address list	—
L1	GIS	460 buildings, 36 roads from OSM	Overpass QL
L2	Topology	14 boundary groups, 70 splitters	distributed_split/1.0.0
L3	Physical	35 handholes, 23 conduit, 14 splices	MST routing + optimizer
L4	Compliance	18 rules, PASS (0 errors, 19 warnings)	Lumos V6 profile
L5	Artifacts	DXF, HTML, BOM, validation report	Rendering pipeline

Key Design Decisions

Microkernel Architecture

Config, errors, and project container live in kernel/. Every other module depends only on the kernel and model — never on each other. This keeps the dependency graph acyclic and each module independently testable.

Tools-First LLM Integration

The LLM never processes raw geometry. 7 baremetal tools expose pre-computed summaries — reducing tokens by 94% compared to sending GeoJSON. LLM suggestions are ephemeral and never written to signed layers.

Integrity Chain

Every layer is SHA-256 hashed and Ed25519 signed. Each layer’s provenance points to the previous layer’s hash. A standalone verifier (zero FiberCAD dependencies) can validate the full chain.

Pluggable Standards

Rules are defined in profile classes (LumosV6Profile, GenericProfile). New ISPs can register custom profiles via register_profile(). Rules are executed per-phase, not monolithically.

3. What Was Built

Complete feature inventory — every capability in the engine.

♦

Planning Engine

Full L0→L4 pipeline: ingest, cluster, place, route, validate. One function call from bbox to compliance report.

♦

Rules Engine (18 rules)

Lumos V6 standards: max drops, run length, spare ports, splitter separation, bend rule, handhole sizing, centralized placement, cul-de-sac routing.

♦

Integrity Chain

Ed25519 signatures, SHA-256 content hashes, provenance links between layers, standalone verifier with zero dependencies.

♦

MCP Tools (7)

project_summary, design_stats, validate_design, validate_element, measure_distance, count_in_area, verify_chain.

♦

LLM Agent

Claude tool_use integration with fallback mode. Never sees raw geometry — works through 7 baremetal tools for 94% token reduction.

♦

Design Optimizer

Pass-through handhole elimination, conduit deduplication, footage reduction. Runs automatically after physical layout.

♦

Fiber Assignment (LLD)

Tube/fiber color assignment, numbering from back of cable, cable naming per Lumos convention.

♦

DXF Output

AutoCAD-compatible DXF with 33 real Lumos blocks, 81 layers, 23 text styles. Paper space layout with title block and viewport.

♦

HTML Map Report

Interactive Leaflet map with 3 basemaps (street, satellite, dark), layer controls, building popups, BOM table, network graph.

♦

BOM Workbook

5-sheet Excel: Summary, Equipment, Conduit, Boundary Groups, Addresses. Styled with openpyxl.

♦

Spatial Index

STRtree wrapper for O(log n) nearest-neighbor and bounding box queries. Used by splitter placement and routing.

♦

Circuit Breaker

Closed/Open/HalfOpen states per endpoint with registry. Protects OSM/Overpass calls from cascade failure.

♦

Security Module

Path sanitization, prompt injection defense, secret redaction for all LLM-facing content.

♦

Client Rules (13)

Source-tagged rules from Lumos V6 docs, training videos, and mattganzak/cad. Phase-based builders for LLM prompt injection.

♦

Multi-Round QA

4-round themed review: coverage, annotation, design, sheet. Each round uses focused rule bundles.

♦

Pluggable Profiles

BaseProfile ABC, LumosV6Profile, GenericProfile. register_profile() API for ISP-specific rule sets.

♦

GeoJSON/Shapefile Import

--geojson CLI flag. Fiona fallback for Shapefile. Auto-detects coordinate reference system.

♦

Cul-de-sac Detection

Dead-end identification in road graph + routing sanity check. Prevents orphaned conduit runs.

4. Rules Engine

18 structural rules from Lumos V6 standards + 13 client rules for LLM guidance.

Structural Validation Rules (Profile-Based)

Rule ID	Description	Source	Severity
`LUMOS-18-MAX-DROPS`	No conduit segment may have more than 6 drops	Lumos V6 Drafting Standards	error
`LUMOS-18-MAX-RUN-LENGTH`	Conduit run ≤ 650 ft absolute maximum	Lumos V6 Drafting Standards	error
`LUMOS-18-MAX-RUN-LENGTH-SOFT`	Conduit run ≤ 500 ft preferred maximum	Lumos V6 Drafting Standards	warning
`LUMOS-13.1-SPARE-PORTS`	1x8 splitter must retain ≥ 2 spare ports	Lumos V6 §13.1	error
`LUMOS-13.2-SPLITTER-SEPARATION`	Splitters in same group ≥ 50 ft apart	Lumos V6 §13.2	warning
`LUMOS-18-BEND-RULE`	At bends: at least one adjacent segment ≤ 150 ft	Training Video Corpus	warning
`LUMOS-13.2-CENTRALIZED`	Splitter placement must be distributed, not centralized	Lumos V6 §13.2	warning
`LUMOS-13.2-MAX-PER-HH`	No more than 2 splitters per handhole	Lumos V6 §13.2	error
`LUMOS-12-HH-SIZING`	Handhole type matches splice/splitter load	Lumos V6 §12	warning
`LUMOS-12-HH-SIZING-3WAY`	Three-way splices require SM or MED handhole	Lumos V6 §12	warning

Client Rules (LLM Prompt Injection)

Rule ID	Section	Phase Tags	Source
`LUMOS_EXPAND_WORKFLOW`	OSP sequence	expand	Permit Design Steps
`LUMOS_JSON_TOPOLOGY`	Topology / coverage	json	Drafting V6
`LUMOS_JSON_HARD_RULES`	Civil / conduit	json	Drafting V6
`LUMOS_JSON_TEXT`	Text / annotation	json	Drafting V6
`LUMOS_JSON_FIBER`	Fiber / splices / TO CO	json	Drafting V6
`LUMOS_JSON_SPLITTERS`	Boundary groups / callouts	json	Drafting V6
`LUMOS_JSON_MATCH_TITLE`	Matchlines / project	json	Drafting V6
`LUMOS_JSON_REFERENCE`	GIS / KMZ	json	V5
`LUMOS_JSON_SELF_CHECK`	Pre-output checklist	json	QC Process
`LUMOS_QA_COVERAGE_STREETS`	Street vs conduit	qa_coverage	QC Permit
`LUMOS_QA_ANNOTATION_PDF`	Annotation / PDF-style	qa_annotation	Drafting V6
`LUMOS_QA_DESIGN_RULES`	Constructability	qa_design	Drafting V6
`LUMOS_QA_SHEET_PROJECT`	Matchlines & project block	qa_sheet	Drafting V6

5. Prior Art Integration

What was adopted from mattganzak/cad and training video analysis.

Lumos Permit Digest

Structured prompts from the mattganzak/cad permit pipeline injected into LLM review context. Provides ISP-specific framing for Claude’s design review.

Client Rules Registry

13 source-tagged rules extracted from drafting standards and QC process. Phase-tagged for selective injection into expand, JSON, and QA phases.

JSON Validator

LLM output normalization adapted from mattganzak/cad. Strips markdown fences, repairs trailing commas, validates JSON structure before processing.

Multi-Round Themed QA

4-pass review sequence (coverage → annotation → design → sheet) inspired by mattganzak/cad QC workflow. Each pass uses focused rule bundles.

Training Video Corpus

Domain knowledge base extracted from Lumos training videos: OSP workflow sequence, drafting conventions, common QC failure patterns.

6. Output Artifacts

Every file the engine produces, from CAD drawings to compliance reports.

File	Format	Description	Size
`L0_input.fiberjson`	JSON	Signed input layer: bounding box, project metadata	—
`L1_gis.fiberjson`	JSON	GIS enrichment: 460 buildings, 36 roads from OSM	—
`L2_topology.fiberjson`	JSON	Network topology: 14 boundary groups, 70 splitters	—
`L3_physical.fiberjson`	JSON	Physical design: 35 handholes, 23 conduit, 14 splices	—
`L4_compliance.fiberjson`	JSON	Validation result: PASS, 0 errors, 19 warnings	—
`design.dxf`	DXF	AutoCAD drawing with 33 Lumos blocks, paper space layout	275 KB
`design_simple.dxf`	DXF	Simplified DXF (no blocks) for compatibility	251 KB
`report.html`	HTML	Interactive Leaflet map + BOM + network graph	216 KB
`bom.xlsx`	XLSX	5-sheet BOM workbook: Summary, Equipment, Conduit, BGs, Addresses	25 KB
`validation.txt`	Text	Human-readable compliance report with rule citations	4 KB
`dxf_viewer.html`	HTML	SVG-based DXF preview with pan/zoom and layer list	5.7 MB

7. Test Coverage

393 tests across 26 test files, all passing in 2.16 seconds.

Test File	Module Covered
`test_boundary_groups.py`	Geographic clustering algorithm
`test_circuit_breaker.py`	Circuit breaker state machine
`test_client_rules.py`	Client rule registry and builders
`test_elements.py`	Domain model dataclasses
`test_fiber_assignment.py`	LLD fiber strand assignment
`test_fiberjson.py`	Layered schema serialization
`test_geojson_import.py`	GeoJSON/Shapefile import
`test_geometry.py`	Haversine, snap, centroid, bbox
`test_ingest.py`	OSM/Overpass/CSV ingest
`test_integration.py`	End-to-end pipeline integration
`test_integrity.py`	Ed25519 signing and verification
`test_json_validator.py`	LLM output normalization
`test_kernel.py`	Kernel config and project container
`test_llm.py`	LLM agent and tool dispatch
`test_network.py`	Road network graph and Dijkstra
`test_optimizer.py`	Design optimizer passes
`test_plan_utils.py`	Planning utility functions
`test_profiles.py`	Pluggable standards profiles
`test_resilience.py`	Rate limiter and checkpoint/resume
`test_routing.py`	MST conduit routing
`test_rules.py`	Validation rule execution
`test_security.py`	Path sanitization, prompt injection
`test_spatial_index.py`	STRtree spatial queries
`test_splitter_placement.py`	1x8/1x4 splitter hierarchy
`test_tools.py`	MCP tool registry and dispatch
`test_workbook.py`	BOM Excel workbook generation

8. Timeline

What was built and when — from scaffold to production-ready engine.

Day 1 — Foundation

Design spec, scaffold, kernel, model, geometry

Project structure, domain model dataclasses, haversine/snap/centroid utilities, road network graph with Dijkstra.

Day 2 — Core Pipeline

FiberJSON, boundary groups, OSM ingest, splitters, routing

Layered schema with integrity hashes, boundary group clustering, OSM/CSV import, 1x8/1x4 splitter placement, MST conduit routing.

Day 3 — MVP Complete

Rules engine, planning service, DXF, HTML report, CLI

Lumos V6 rules profile, full L0→L4 orchestration, AutoCAD DXF output, Leaflet HTML report, CLI entry point, end-to-end integration tests.

Week 1 — Hardening

Additional rules, security, Ed25519, BOM, MCP tools

Splitter separation, bend rule, handhole sizing. Security module. Ed25519 integrity chain with standalone verifier. BOM workbook. 7 MCP-compatible baremetal tools.

Week 1 — LLM Layer

LLM agent, resilience, enhanced HTML, real DXF blocks

Claude tool_use agent with fallback. Token bucket rate limiter. Tabbed HTML report with satellite basemap. 33 real Lumos blocks extracted from template DWG.

Week 2 — Production

Prior art, client rules, optimizer, fiber assignment, spatial index

mattganzak/cad adoption (permit digest, client rules, JSON validator, themed QA). Design optimizer. LLD fiber strand assignment. STRtree spatial index. Pluggable standards profiles.