feat: major refactor, performance improvements, reduction in code.

Author: jeshernandez

.gitignore

@@ -44,3 +44,8 @@
 *.claude
 CLAUDE.md
 AGENTS.md
+CLONE_OPTIMIZATION_*
+CONFIG_MIGRATION_*
+PHASE_*
+VALIDATION_CHECKLIST*
+COPYRIGHT_HEADERS.md

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Jesse Hernandez
+Copyright (c) 2025 Jesse Hernandez, Digital Hand LLC
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

LICENSES/BSD-2-Clause.txt

@@ -0,0 +1,25 @@
+BSD 2-Clause License
+
+Copyright (c) <year>, <copyright holder>
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

LICENSES/GPL-2.0-only.txt

@@ -0,0 +1,71 @@
+# License Policy
+
+This repository currently contains a mix of source provenance and licenses.
+
+## Source-Of-Truth Rules
+
+1. The effective license for a file is the file-level SPDX header.
+2. If a file has no SPDX header, treat that as a compliance gap and add one.
+3. Existing third-party notices must be preserved.
+
+## License Documents
+
+- MIT license: `LICENSE`
+- GPL-2.0-only text: `LICENSES/GPL-2.0-only.txt`
+- BSD-2-Clause text: `LICENSES/BSD-2-Clause.txt`
+- Repository notice: `NOTICE`
+
+## New Code Policy (Digital Hand)
+
+For brand-new files authored in this repository:
+
+- Use `SPDX-License-Identifier: MIT`.
+- Use Digital Hand copyright notice.
+- Header template:
+
+```cpp
+/* SPDX-License-Identifier: MIT */
+/*
+ * Copyright (c) 2026, Digital Hand LLC.
+ */
+```
+
+## Derived / Upstream-Origin Code Policy
+
+For files derived from upstream/original PiTrac code:
+
+- Keep existing upstream SPDX and copyright notices.
+- Add Digital Hand copyright lines for substantial new contributions.
+- Do not remove upstream notices without explicit legal approval.
+
+Example:
+
+```cpp
+/* SPDX-License-Identifier: GPL-2.0-only */
+/*
+ * Copyright (C) 2022-2025, Verdant Consultants, LLC.
+ * Copyright (c) 2026, Digital Hand LLC.
+ */
+```
+
+## Third-Party Imported Code
+
+- Keep original SPDX/license headers exactly as provided.
+- Do not replace with MIT headers.
+- Keep required attribution/license files in-tree.
+
+## Practical Workflow
+
+1. Determine whether the file is brand-new or derived.
+2. Apply the matching header template.
+3. Keep SPDX and copyright line ordering consistent.
+4. Run a quick audit before release:
+
+```bash
+rg -n "SPDX-License-Identifier|Copyright" -S src pitrac-cli
+```
+
+## Notes
+
+- Refactor percentage does not automatically relicense inherited code.
+- Fork status also does not change notice obligations.

LICENSE_POLICY.md

@@ -0,0 +1,15 @@
+This repository contains a mix of code under different licenses.
+
+License resolution order:
+1. File-level SPDX header is authoritative for that file.
+2. If a file has no SPDX header, treat that as a compliance gap.
+
+Primary license documents in this repository:
+- MIT: LICENSE
+- GPL-2.0-only: LICENSES/GPL-2.0-only.txt
+- BSD-2-Clause: LICENSES/BSD-2-Clause.txt
+
+Attribution and provenance:
+- Upstream/third-party notices are preserved in their source files.
+- Net-new Digital Hand authored code should use MIT + Digital Hand header.
+- See LICENSE_POLICY.md and COPYRIGHT_HEADERS.md for contributor rules.

NOTICE

@@ -29,7 +29,16 @@ Same C++ code base as https://github.com/PiTracLM/PiTrac. However, this project
 - [Known Issues](#known-issues)
 - [System Sequence Diagram](#system-sequence-diagram)
 - [Architecture Diagrams](#architecture-diagrams)
+  - [Runtime Architecture](#runtime-architecture)
+  - [Data Flow Overview](#data-flow-overview)
+  - [Ball Hit Flow](#ball-hit-flow)
+  - [Hardware Topology](#hardware-topology)
+  - [Module Dependencies](#module-dependencies)
+  - [Calibration Flows](#calibration-flows)
 - [Simulator Data](#simulator-data)
+- [Licensing](#licensing)
+  - [License Files](#license-files)
+  - [File-Level SPDX Rules](#file-level-spdx-rules)
 - [Additional Resources](#additional-resources)
 
 ## What this is not 
@@ -420,3 +429,81 @@ See [`.github/workflows/ci.yml`](.github/workflows/ci.yml) for CI configuration.
 ## Known Issues
 
 - **ONNX Runtime Eigen hash mismatch** – The upstream `onnxruntime-1.17.3` source bundles Eigen via `cmake/external/eigen.cmake`, but the published hash no longer matches the live tarball. When the `pitrac-cli install` command or a manual build run `cmake`, the fetch step fails with a message similar to `HASH mismatch for file: eigen-...`. To work around this, edit `~/src/onnxruntime-1.17.3/cmake/external/eigen.cmake` (or wherever you unpacked the sources) and update the `URL_HASH` line to `SHA1=32b145f525a8308d7ab1c09388b2e288312d8eba`, then re-run the build. Track the upstream ONNX Runtime issue for a permanent fix.
+
+## System Sequence Diagram
+
+High-level lifecycle from startup through shot processing:
+
+![PiTrac system sequence](assets/images/basic_ssd.png)
+
+## Architecture Diagrams
+
+### Runtime Architecture
+
+Current refactored runtime view:
+
+![PiTrac runtime architecture](assets/images/architecture-overview.png)
+
+### Data Flow Overview
+
+Configuration, runtime IPC, simulator send path, and artifact writes:
+
+![PiTrac data flow overview](assets/images/data-flow-overview.png)
+
+### Ball Hit Flow
+
+Camera1 detection to camera2 capture to simulator output:
+
+![PiTrac ball hit flow](assets/images/golf-simulator-ball-hit-flow.png)
+
+### Hardware Topology
+
+Single-Pi primary hardware topology with optional legacy dual-Pi support:
+
+![PiTrac hardware topology](assets/images/hardware-topology.png)
+
+### Module Dependencies
+
+Current module dependency map for runtime libraries and entrypoints:
+
+![PiTrac module dependencies](assets/images/module-dependencies.png)
+
+### Calibration Flows
+
+Auto-calibration process for each camera:
+
+![PiTrac camera1 calibration flow](assets/images/calibration-flow-camera1.png)
+
+![PiTrac camera2 calibration flow](assets/images/calibration-flow-camera2.png)
+
+## Simulator Data
+
+- Runtime shot results are emitted through the ActiveMQ topic `Golf.Sim`.
+- GSPro integration uses `sim/common` and `sim/gspro` with TCP output to GSPro (default port `921`).
+- Result/debug images are written to the configured web share and logging directories (for example `~/LM_Shares/Images` and `~/PiTracLogs`).
+
+## Licensing
+
+This repository is mixed-license and uses file-level SPDX identifiers.
+
+### License Files
+
+- MIT: [`LICENSE`](LICENSE)
+- GPL-2.0-only: [`LICENSES/GPL-2.0-only.txt`](LICENSES/GPL-2.0-only.txt)
+- BSD-2-Clause: [`LICENSES/BSD-2-Clause.txt`](LICENSES/BSD-2-Clause.txt)
+- Repository notice: [`NOTICE`](NOTICE)
+
+### File-Level SPDX Rules
+
+- The SPDX header on each file is the source of truth for that file's license.
+- Preserve upstream/third-party notices in derived files.
+- Net-new Digital Hand code should use MIT headers.
+- Contributor policy: [`LICENSE_POLICY.md`](LICENSE_POLICY.md)
+- Header templates: [`COPYRIGHT_HEADERS.md`](COPYRIGHT_HEADERS.md)
+
+## Additional Resources
+
+- Build internals: [`BUILD_SYSTEM.md`](BUILD_SYSTEM.md)
+- Developer workflows: [`DEVELOPER_QUICKSTART.md`](DEVELOPER_QUICKSTART.md)
+- Hook setup: [`hooks/README.md`](hooks/README.md)
+- Diagram sources: `assets/diagram/*.puml`

README.md

@@ -1,78 +1,69 @@
 @startuml
-title PiTrac Architecture (Services + Runtime Components)
+title PiTrac-Light Runtime Architecture (Refactored)
 
 skinparam shadowing false
 skinparam backgroundColor white
 skinparam componentStyle rectangle
 skinparam packageStyle rectangle
 skinparam defaultTextAlignment center
 
-actor "User" as user
+actor "Operator" as user
 
 node "Raspberry Pi OS (arm64)" as pi {
-  package "systemd Services" {
-    [pitrac-web.service] as websvc
-    [activemq.service] as amqsvc
+  package "CLI and Operations" {
+    [pitrac-cli] as cli
+    [RunScripts\n(src/RunScripts/*.sh)] as scripts
   }
 
-  package "Web Layer (Python FastAPI)" as web {
-    [Browser UI\nDashboard/Calibration/Testing] as browser
-    [REST API + WebSocket\nserver.py] as api
-    [PiTracProcessManager\n(pitrac_manager.py)] as procman
-    [CalibrationManager] as calman
-    [ActiveMQ Listener\n(STOMP 61613)] as stlistener
-    [ShotDataStore + Parser] as datastore
-    [ConfigurationManager] as cfgman
+  package "Launch Monitor Runtime (C++)" {
+    [pitrac_lm\n--system_mode camera1\nFSM + hit detection] as cam1
+    [pitrac_lm\n--system_mode camera2\ntriggered capture] as cam2
+    [ConfigurationManager\n(JSON + env overrides)] as cfgmgr
+    [ActiveMQ IPC Adapter\nproducer + consumer] as ipc
+    [Simulator Bridge\nsim/common + sim/gspro] as sim
+    [Artifact Writer\nGsUISystem + LoggingTools] as artifactsvc
   }
 
-  package "Core LM Runtime (C++ pitrac_lm)" as lm {
-    [Camera1 Process\nFSM + hit detection] as cam1
-    [Camera2 Process\ncapture/IPC responder] as cam2
-    [IPC System\n(OpenWire producer/consumer)] as ipc
-    [Simulator Interfaces\nGSPro TCP sockets] as simsock
-  }
-
-  database "ActiveMQ Broker\nOpenWire 61616 / STOMP 61613" as amq
+  database "ActiveMQ Broker\nOpenWire tcp://*:61616\nTopic: Golf.Sim" as amq
 
-  folder "~/.pitrac/config" as cfgfiles
-  folder "~/.pitrac/logs + ~/.pitrac/run" as runtimedirs
-  folder "~/LM_Shares/Images" as images
+  folder "~/.pitrac/config\npitrac.env\nuser_settings.json\ngolf_sim_config.json" as cfg
+  folder "~/LM_Shares/Images\n~/PiTracLogs" as files
 }
 
 cloud "Simulator PC" as simpc {
   [GSPro] as gspro
 }
 
-user --> browser
-browser --> api : HTTP :8080\nREST + /ws
+cloud "Optional External Tools" as external {
+  [Golf.Sim topic subscriber\n(OpenWire/CMS)] as sub
+}
 
-websvc --> api : starts uvicorn main.py
-amqsvc --> amq : broker runtime
+user --> cli : setup / run / service
+user --> scripts : optional direct execution
 
-api --> procman
-api --> calman
-api --> cfgman
-api --> stlistener
-stlistener --> datastore
-datastore --> api : websocket broadcasts
+cli --> cfg : env setup + config init
+cli --> amq : broker checks / service control
+cli --> cam1 : launch camera1 modes
+cli --> cam2 : launch camera2 modes
 
-procman --> cam1 : spawn/stop process
-procman --> cam2 : spawn/stop process\n(single-Pi mode)
-procman --> cfgman : generate config + CLI/env
-procman --> runtimedirs : PID/log files
+scripts --> cam1
+scripts --> cam2
 
-cfgman --> cfgfiles : user_settings.json\ncalibration_data.json\ngenerated_golf_sim_config.json
+cam1 --> cfgmgr
+cam2 --> cfgmgr
+cfgmgr --> cfg : load + persist config values
 
 cam1 --> ipc
 cam2 --> ipc
-ipc --> amq : topic Golf.Sim
-stlistener --> amq : subscribe /topic/Golf.Sim
+ipc --> amq : publish / consume IPC messages
+
+cam1 --> sim : shot metrics
+sim --> gspro : TCP :921
 
-cam1 --> simsock
-simsock --> gspro : TCP 921
+cam1 --> artifactsvc
+cam2 --> artifactsvc
+artifactsvc --> files : write PNGs + logs
 
-cam1 --> images : shot/debug images
-cam2 --> images : capture images
-api --> images : /images + /api/images
+amq --> sub : status / hit / control messages
 
 @enduml

assets/diagram/architecture-overview.puml

@@ -1,5 +1,5 @@
 @startuml
-title PiTrac Camera 1 Calibration Flow
+title Camera 1 Auto-Calibration Flow (Current Runtime)
 
 skinparam shadowing false
 skinparam backgroundColor white
@@ -12,27 +12,28 @@ skinparam activity {
 
 start
 
-:Optional pre-check:\nPOST /api/calibration/ball-location/camera1;
-:Optional still capture:\nPOST /api/calibration/capture/camera1;
-:Validate image quality in\n~/LM_Shares/Images;
+:Ensure runtime prerequisites:\n- pitrac-cli validate env\n- pitrac-cli service broker start;
+:Optional image sanity check:\npitrac-cli run still --camera 1;
 
-:POST /api/calibration/auto/camera1;
-:CalibrationManager creates session\nfor expected keys:\n- gs_config.cameras.kCamera1FocalLength\n- gs_config.cameras.kCamera1Angles;
-:Launch pitrac_lm\n--system_mode=camera1AutoCalibrate\n(+ --run_single_pi in single mode);
+:Run auto-calibration:\npitrac-cli run auto-calibrate --camera 1;
+:CLI launches pitrac_lm with\n--system_mode camera1AutoCalibrate\nand common args;
 
-:Hybrid completion detection:\n1) API callbacks\n2) Process exit\n3) Timeout (40s);
+:pitrac_lm startup:\nload config + init camera + IPC + GPIO;
 
-if (Both callback keys received?) then (yes)
-  :PUT /api/config updates camera1\nfocal length + angles;
-  :Write values into\n~/.pitrac/config/calibration_data.json;
-  :Regenerate\n~/.pitrac/config/generated_golf_sim_config.json;
+:Capture multiple samples\n(kNumberPicturesForFocalLengthAverage);
+:Compute average focal length;
+
+if (Ball detection / focal length valid?) then (yes)
+  :Determine camera angles;
+  :Update config tree keys:\n- gs_config.cameras.kCamera1FocalLength\n- gs_config.cameras.kCamera1Angles;
+  :Backup current config file;
+  :Write updated golf_sim_config.json;
+  :Save calibration artifacts\nto logging/image directories;
+  :Exit success;
 else (no)
-  :Fallback to process result\nand output parsing for failure markers;
+  :Abort calibration with error logs;
+  :Keep previous effective values;
 endif
 
-:Status exposed via\nGET /api/calibration/status;
-:Calibration values exposed via\nGET /api/calibration/data;
-:Validate resulting calibration images\nin ~/LM_Shares/Images;
-
 stop
 @enduml