FiberCAD Technical Architecture

1. System Overview

FiberCAD is a fiber network planning engine built on a microkernel + plugin architecture. It automates the full FTTH distributed split design workflow: from raw address data to construction-ready DXF output with cryptographic integrity verification.

2. Microkernel Architecture

The kernel provides domain-agnostic services. Domain modules register as plugins and are dispatched through a chain-of-responsibility pattern.

Kernel Modules

Dispatch Pattern

class DispatchResult:
    HANDLED = "handled"
    NOT_HANDLED = "not_handled"

class Dispatcher(Protocol):
    def dispatch(self, tool_name: str, args: dict) -> tuple[str, Any]:
        """Returns (HANDLED, result) or (NOT_HANDLED, None)"""
        ...

# Chain: ingest -> planning -> rules -> output -> integrity
def dispatch_chain(dispatchers: list[Dispatcher], tool_name: str, args: dict):
    for d in dispatchers:
        status, result = d.dispatch(tool_name, args)
        if status == DispatchResult.HANDLED:
            return security.strip_prompt_injection(result)  # post-processing
    raise ToolNotFoundError(tool_name)

3. Layered Data Architecture (FiberJSON)

Data flows through graduated enrichment layers. Each layer is a separate file, building on the previous. This enables selective regeneration, independent versioning, and full provenance tracking.

Layer Schema Versions

4. Integrity Chain & Signing

Every layer file contains an _integrity header with SHA-256 content hash, Ed25519 signature, and provenance link to the previous layer.

{
  "_integrity": {
    "version": "1",
    "content_hash": "sha256:a1b2c3...",
    "signature": "ed25519:x9y8z7...",
    "signer": {
      "id": "fibercad-engine/1.0.0",
      "public_key": "ed25519:pub_abc123..."
    },
    "timestamp": "2026-04-17T14:32:00Z",
    "provenance": {
      "previous_layer": "L1_gis.fiberjson",
      "previous_hash": "sha256:d4e5f6...",
      "previous_signature_valid": true
    },
    "generation": {
      "tool_version": "0.1.0",
      "algorithm_versions": {
        "boundary_groups": "1.0.0",
        "routing": "1.0.0"
      },
      "profile": "lumos_v6"
    }
  }
}

Verification

1. Canonicalize content (sorted keys, no whitespace)
2. Verify SHA-256 hash matches
3. Verify Ed25519 signature using public key from L0 (trust anchor)
4. Verify provenance hash matches actual hash of previous layer
5. Walk the full chain L0 → L4

Key Management

• Per-project Ed25519 keypair generated at project creation
• Private key: ~/.config/fibercad/keys/<project_id>.key (mode 0600)
• Public key embedded in L0 as trust anchor
• Re-keying requires re-signing entire chain from L0
• LLM suggestions are ephemeral — never written to signed layers

5. Planning Algorithms

5.1 Boundary Group Generation O(n log n)

Constrained road-network agglomerative clustering. Partitions addresses into groups of ~32 for one 1x8 splitter each, with ~4 spare ports.

1. Build road graph from L1 (nodes = intersections, edges = road segments)
2. Snap each address to nearest road segment
3. Compute road-network distances (not Euclidean — houses across a highway are far apart)
4. Agglomerative clustering: merge nearest contiguous clusters until size ≈ 32
5. Generate boundary polygon (convex hull expanded to parcel boundaries)

5.2 Splitter Placement O(n)

Two-stage: 1x8 at boundary group centroid (road-network), 1x4 at sub-cluster centroids. All snapped to nearest parcel line per standards.

5.3 Conduit Routing O(V × E log V)

Greedy Steiner tree approximation on road network. MST of splitter positions using Dijkstra road-network distances, mapped back onto actual road segments. Post-processing inserts handholes (every ≤500ft), assigns drops (max 6), verifies no T-connections.

5.4 Sanity Checks

Run between L2→L3 transition before committing the layer:

• No zero-address groups
• No disconnected road segments (islands)
• Detour ratio (route / crow-fly) within bounds
• No isolated nodes in the network graph

6. Baremetal Tool Layer (MCP-Compatible)

Deterministic tools that LLMs call via tool_use. The LLM never sees raw geometry — it receives structured summaries (~30 tokens instead of 3,000).

7. Rules Engine

Provider standards are encoded as pluggable profiles. The engine dispatches rules, returns typed ValidationResult structs, and never touches the filesystem.

Lumos V6 Rule Set (15 rules implemented, 4 planned)

Each violation includes: rule ID, severity (error/warning/info), affected element ID, human-readable message, and contextual fix guidance (no LLM needed for the explanation).

8. Output Generation

DXF (AutoCAD)

Generated via ezdxf. Layer mapping follows Lumos conventions:

HTML Map Report

Self-contained HTML file with embedded Leaflet.js. All design layers on aerial imagery, clickable popups, validation results panel, design statistics. Zero server dependency.

BOM Workbook

Excel workbook (openpyxl): equipment summary, conduit footage, cable counts, address assignments, material cost estimate.

9. Security Model

Input Sanitization

• OSM strings: strip control characters, path traversal sequences (OSM is publicly editable)
• CSV input: reject formula injection prefixes (=, +, -, @)
• Coordinates: validate lat ∈ [-90, 90], lon ∈ [-180, 180], within project bbox

Prompt Injection Defense

• strip_prompt_injection applied at dispatch post-processing layer
• All tool results sanitized before returning to LLM context

DXF Output Safety

• No XREF/XDATA fields from external input
• All strings bounded to printable ASCII, max length enforced

10. Performance Architecture

11. LLM Integration

The LLM (Claude) is an optional review layer, not a core dependency. It calls baremetal tools and reasons about structured summaries.

What the LLM does

• Reviews validation results and explains trade-offs
• Suggests optimization: "This street has 3 conduit runs, suggest consolidation"
• Generates natural-language design narratives for documentation
• Answers designer questions about the plan

What the LLM never does

• Process raw geometry (gets summaries from tools)
• Perform calculations (tools do math)
• Write to signed layers (suggestions are ephemeral)
• Make final design decisions (advises the operator)

12. Rust Migration Path

The architecture is designed for migration to Rust (Go as fallback):

• model/ — dataclasses map directly to Rust structs
• planning/ — pure functions, no framework deps, map to Rust functions
• rules/ — typed ValidationResult maps to Rust enum
• network graph — dict-adjacency designed to map to petgraph
• tools/ — MCP schemas are language-agnostic JSON
• FiberJSON — JSON interchange format, language-independent