FiberCAD Architecture Evolution Report

1. Executive Summary

FiberCAD builds on lessons from a prior CAD patch pipeline (mattganzak/cad, 22,700 LOC) that took a fundamentally different approach — editing existing drawings rather than generating new designs. FiberCAD then started as a vision for a full cloud-native GIS platform, evolved through four major architectural pivots driven by timeline constraints, domain expertise extraction, and rigorous architecture review. The result is a focused design generator that complements the prior patch system and outperforms the original scope on every dimension that matters to the customer.

2. Prior Art: The CAD Patch Pipeline (mattganzak/cad)

Before FiberCAD, a separate system was built to automate fiber design work. This system (mattganzak/cad, 22,700 LOC across 3 modules) took a fundamentally different approach: patching existing drawings rather than generating new designs from scratch.

Architecture

Existing DWG ──► C# AutoCAD Plugin ──► JSON Snapshot ──► LLM (DeepSeek)
                  (EXPORTDWGFULLJSON)                      │
                                                     Design Understanding
                                                     Edit Brief
                                                     Patch JSON
                                                           │
                                                     ◄─────┘
Validated Patch ──► C# Plugin ──► Updated DWG ──► Integrity Check
                   (APPLYJSONPATCH)

What It Did

Three Modules

Strengths of This Approach

• Works with existing drawings. Takes a partially complete DWG and adds/edits content — doesn't require starting from scratch.
• Protected geometry concept. Buildings, parcels, roads, and template elements are locked; only design content can be edited. Integrity verified after every patch.
• CAD-native. Uses a real C# AutoCAD plugin for export/import — handles full DWG fidelity (blocks, attributes, linetypes, paper space).
• QA loop. Iterative patch → validate → apply → re-export cycle (up to 10 rounds).
• Lumos standards documented. Comprehensive client standards guide mapping all V6 rules to JSON schema fields.

Limitations Identified

What FiberCAD Adopted

• Protected geometry concept → evolved into the integrity chain (signed layers, not geometry locking)
• Lumos standards documentation → directly informed the rules engine (all 12+ rules from the guide are implemented)
• Patch validation pattern → evolved into the self-validation rules engine (deterministic, not LLM-driven)
• QA loop concept → inspired the layered regeneration architecture (change L2 algorithm, L3-L4 regenerate)

What FiberCAD Changed

• No AutoCAD runtime dependency. Generates DXF files that AutoCAD opens, but doesn't require AutoCAD to run.
• Deterministic planning, not LLM patching. Algorithms place every splitter, route every conduit, size every handhole. The LLM reviews the result, it doesn't generate it.
• Starts from raw data, not existing drawings. Fetches GIS data from OSM, plans the network, generates construction output. No pre-existing DWG required.
• Cross-platform. Python on Linux/Mac/Windows. No C# plugin, no COM bridge.
• 393 tests. Every rule, algorithm, and output format has automated test coverage.

3. The Original Vision: Full Cloud-Native GIS Platform

The project started with a research phase: codebase review (14 AutoLISP scripts, Lumos V6 standards, Hampton Heights project files, 2.1GB training videos) and competitive analysis (3-GIS, VETRO FiberMap, IQGeo/Comsof, FibPlanner, OSPInsight). The initial architecture was designed as a full-scale 3-GIS replacement:

                     WEB CLIENT
  Map Canvas (MapLibre GL) + Design Canvas (Fabric.js)
  Real-time collaboration (WebSocket)
                        |
                    API LAYER
  REST + WebSocket + File I/O (DWG/PDF/GeoJSON)
     |       |       |       |       |       |
  GIS     Graph    Rule    Doc     LLM    Equipment
  Engine  Engine   Engine  Gen    Agent   Catalog
                        |
                   PostGIS DB
                 (Spatial + Network)

What This Entailed

The build sequence was planned across 5 phases over several months:

• Phase 1: PostGIS schema + web map canvas + basic element placement
• Phase 2: Network graph engine + rules engine + constraint validation
• Phase 3: Auto-planning algorithms + LLM integration
• Phase 4: PDF/DXF document generation + splice diagrams + BOM
• Phase 5: Multi-user collaboration + mobile field app + project management

What Was Right About It

• The domain analysis was thorough and correct — the competitive gaps identified (Esri dependency, no provider-specific rules, no self-validation) remain the differentiators
• The module decomposition (GIS, Graph, Rules, Doc, LLM, Catalog) maps directly to the packages we built
• The target market (mid-market orgs priced out of 3-GIS) is validated

What Was Wrong About It

• Wrong delivery vehicle. The customer works in AutoCAD. A web canvas is a new tool they'd need to learn. DXF output into their existing workflow is immediately useful.
• Wrong timeline. React + PostGIS + WebSocket + auth + deployment before any fiber planning logic exists. Infrastructure before value.
• Wrong dependency chain. The ODA SDK requires licensing. PostGIS requires hosting. WebSocket requires a server. Each dependency adds weeks before the first network plan is generated.
• Wrong LLM role. Assumed LLM would be the intelligence layer. In practice, deterministic tools are more reliable, faster, and work offline.

4. Pivot 1: Cloud Platform to Python CLI Engine

With the 3-day deadline established, the cloud platform was scoped down to a Python CLI engine (Approach C from brainstorming: engine + DXF output + HTML map report). This was the first working Python architecture:

fibercad/
├── cli.py                    # argparse entry point
├── ingest/
│   ├── osm.py                # Overpass API fetch
│   ├── geocode.py            # Nominatim geocoding
│   └── importers.py          # CSV/GeoJSON loaders
├── model/
│   ├── network.py            # Road graph + Dijkstra
│   ├── elements.py           # Equipment dataclasses
│   ├── geometry.py           # haversine, snap, centroid
│   └── schema.py             # Single FiberJSON schema
├── planning/
│   ├── boundary_groups.py    # Clustering algorithm
│   ├── splitter_placement.py # 1x8/1x4 placement
│   ├── routing.py            # Conduit routing
│   └── optimizer.py          # Cost optimization
├── rules/
│   ├── engine.py             # Rule checker
│   └── profiles/lumos_v6.py  # 12 rules from standards doc
├── output/
│   ├── fiberjson.py          # JSON serializer (SHA-256 only)
│   ├── dxf.py                # DXF with primitive shapes
│   ├── report_html.py        # Simple Leaflet map
│   └── workbook.py           # BOM Excel
└── llm/
    ├── client.py             # Claude API client
    └── design_review.py      # LLM sends/receives raw data

What This Version Had

• Working pipeline: bbox → OSM fetch → planning → DXF + HTML
• 12 rules from the written Lumos V6 standards document
• Single monolithic FiberJSON file (all data in one blob)
• SHA-256 hash but no signatures, no provenance chain
• Primitive DXF shapes (squares for handholes, circles for loops)
• Simple HTML report (one page, no tabs, no layer controls)
• LLM received raw geometry data directly

What This Version Was Missing

Two things then happened that transformed this into the final architecture:

1. Architecture review against Rapsody patterns — identified 21 specific gaps across consistency, reliability, security, performance, and transparency (Section 7)
2. Video corpus analysis — 5 training videos transcribed, revealing 9 critical rules not in any written standard (Section 6)

5. Pivot 2: First Python to Production Architecture

The architecture review (informed by the Rapsody sister project's microkernel patterns) restructured the codebase from a flat script collection into a layered, production-grade engine.

What Was Added

6. Pivot 4: Monolithic Schema to Layered Cake

{
  "type": "FiberNetwork",
  "network": {
    "elements": [...],
    "boundary_groups": [...],
    "addresses": [...]
  },
  "validation": { ... }
}

L0_input.fiberjson      (what we're given)
L1_gis.fiberjson        (what exists there)
L2_topology.fiberjson   (network decisions)
L3_physical.fiberjson   (placed on ground)
L4_compliance.fiberjson (validated)