Refactor to simplify code base and identify regression

[majormer]

---

title: Pre-Refactor Architecture Analysis
type: ARCH
date: 2026-01-14
status: WIP
category: Architecture
tags: [architecture, refactor, structure, analysis]
related: [ARCH_Adapter_Lifecycle.md, ANALYSIS_Configuration_System.md]

Pre-Refactor Architecture Analysis

Snapshot Metrics

Line counts (captured via PowerShell on 2026-01-14):

• Code files: 861
• Code lines: 209,962
• Docs files: 190
• Docs lines: 41,395

Scope includes: *.h, *.hpp, *.cpp, *.c, *.cs, *.inl, *.md.

Current Source Layout Observations

1) Parallel Utility folders

There are both Utility/ and Utilities/ directories at the top level. This splits helper code across similarly named locations and makes discovery inconsistent.

• Utility/SFNetworkHelper.*
• Utilities/SFConveyorConnectionHelper.*

2) Feature vs Service boundaries are blurred

There is a Features/ folder, but large feature logic also lives under Services/ and Subsystem/. Example: Auto-Connect runs in Services/SFAutoConnectService.cpp but depends on Features/PipeAutoConnect/*, making ownership and boundaries unclear.

3) Subsystem is a central hub

SFSubsystem.h includes a wide array of feature headers, services, holograms, and helpers. This creates tight coupling and makes dependency direction hard to reason about.

4) Helpers are dispersed

“Helper” functionality lives across Helpers/, Services/, Utilities/, Utility/, and Subsystem/. There is no single location for shared utilities.

5) Public/Private usage appears underutilized

Public/ and Private/ exist, but most headers are placed outside these folders. This limits the value of formal public/private API boundaries.

6) Hologram surface area is large

Holograms/ contains many classes and subfolders, with belt placement/spline logic appearing in multiple locations. This likely drives “multiple ways to do the same thing.”

7) Feature locality is inconsistent

Feature folders exist but are not consistently used as the “single home” for that feature’s logic, helpers, and types. This increases search cost and reduces reuse.

Early Refactor Targets (Direction Only)

These are not changes yet—just candidate goals inferred from the layout:

1. Consolidate shared helpers into a single Shared/ or Common/ location.
2. Move feature logic under Features/<FeatureName>/Public|Private to enforce boundaries.
3. Reduce SFSubsystem includes by using forward declarations and feature accessors.
4. Establish a single belt placement/spline pipeline and make other features call it.

Subsystem Slimming Goal

Reduce USFSubsystem to a thin facade that owns a single core system/module and delegates feature initialization. The current subsystem is a high‑fan‑in include hub; the target is a small lifecycle wrapper with forward declarations only and feature accessors.

De-duplication Opportunities (Belt/Pipe/Chain)

1) Preview helper lifecycle is parallel

FBeltPreviewHelper and FPipePreviewHelper both implement the same core lifecycle: spawn hologram, apply build class, mark as child, update spline endpoints, hide/show, destroy via helper service. This can be unified under a shared base (e.g., FConduitPreviewHelper) with per‑type routing hooks.

2) Routing logic split across helpers and holograms

Belts use TryUseBuildModeRouting() + AutoRouteSplineWithNormals() on ASFConveyorBeltHologram, while pipes use SetupPipeSpline() on ASFPipelineHologram. A shared routing interface (e.g., IRoutableSplinePreview) would let both helpers call a single path and reduce duplicated update/visibility logic.

3) Multiple belt build paths

Belts are built from preview in SFAutoConnectService::BuildBeltFromPreview() using AFGBuildableConveyorBelt::Respline() while previews use hologram routing. This is a prime source of mismatch and should be consolidated so the “build” step always consumes a single, canonical spline data contract.

4) Chain actor handling scattered

Snapped connections are set in ASFConveyorBeltHologram::SetupBeltSpline() and also in preview helper setup. A single “connect + chain registration” helper should own this to avoid diverging behavior between preview/build.

5) Child destruction pattern repeated

Both helpers manually guard destruction and call FSFHologramHelperService::QueueChildForDestroy(). This is reusable and should live in a shared child‑hologram lifecycle utility.

Unified Conduit Pipeline (Belt/Pipe/Power)

Establish a single pipeline for “conduit” placement that all features call (Auto‑Connect, Extend, Stackable poles, etc.). This standardizes preview, build, and post‑build behavior for belts, pipes, and power lines.

Phases

1. Preview: Spawn/update hologram spline, apply materials, manage child registration.
2. Build: Spawn buildable from canonical spline data (not feature‑specific copies).
3. Post‑Build: Chain actor fixups, connector validation, visibility/material reconciliation.

Reusable Core Modules (Targets)

• Shared/Conduits/ for pipeline orchestration and common lifecycle helpers.
• Shared/SplineRouting/ for routing contracts (belt/pipe/power specific adapters).
• Shared/ChildHolograms/ for spawn/visibility/cleanup behaviors.

Expected Outcome

• Fixing a chain‑actor or spline bug once updates all belt/pipe/power flows.
• Feature code stays thin and delegates to the shared pipeline.

Feature Definitions (Developer-Verified)

These are the canonical Smart! features as defined by the developer:

1. Scaling
2. Conveyor Auto-Connect
3. Pipe Auto-Connect
4. Power Auto-Connect
5. Extend
6. Upgrade

Clarifications

• Arrows are a part of Scaling (visualization only).
• Camera is a feature but lives in another mod.
• Controls are input modality, not a feature.
• Dismantle is planned, not current.
• GridCounters are Scaling UX, not a feature.
• RadarPulse is internal debug tooling.
• Recipe is part of Scaling.
• Restore is an old feature; rebrand as Smart! Presets (saved build recipe + grid counts + transforms, e.g., “Standard train corkscrew ramp”).

Branding (Proposed Names)

• Smart! Scaling
• Smart! Conveyor Auto-Connect
• Smart! Pipe Auto-Connect
• Smart! Power Auto-Connect
• Smart! Stackable Conveyor Pole Auto-Connect
• Smart! Stackable Pipe Pole Auto-Connect
• Smart! Extend
• Smart! Upgrade

---

This document records pre-refactor findings only. No structural changes have been applied yet.