From 4e149d1369fff2cf90dd47e880158dc2119b667c Mon Sep 17 00:00:00 2001
From: Fam Zheng <fam@euphon.net>
Date: Sun, 24 Aug 2025 11:58:48 +0100
Subject: [PATCH] add doc/alg-cleanup.md

---
 doc/alg-cleanup.md | 161 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 161 insertions(+)
 create mode 100644 doc/alg-cleanup.md

diff --git a/doc/alg-cleanup.md b/doc/alg-cleanup.md
new file mode 100644
index 0000000..3e5c80b
--- /dev/null
+++ b/doc/alg-cleanup.md
@@ -0,0 +1,161 @@
+# ALG Directory Cleanup Plan
+
+This document tracks the cleanup work for the `alg/` directory to remove unused code and simplify the build system.
+
+## 🎯 **Cleanup Goals**
+
+- Remove unused command functions and infrastructure code
+- Simplify the Makefile by removing unused conditional builds
+- Reduce codebase size and complexity
+- Maintain core QR code functionality
+
+## 🗑️ **Files/Code to Remove**
+
+### 1. **Unused Command Functions in `qrtool.cpp`**
+
+These functions are defined but never called:
+
+```cpp
+// Remove these unused functions:
+static int detect_cmd(char **argv, int argc)      // Lines ~26-40
+static int dot_cmd(char **argv, int argc)         // Lines ~65-80  
+static int roi_verify_cmd(char **argv, int argc)  // Lines ~100-120
+```
+
+**Impact**: Reduces executable size, removes unused QR detection and ROI verification code.
+
+### 2. **Unused Infrastructure Code**
+
+#### HTTP Server (`http.h`, `http.cc`)
+- **Status**: Never called, only includes `httplib.h`
+- **Dependencies**: `httplib.h` (304KB header file)
+- **Action**: Remove both files
+
+#### gRPC Server (`fileprocess.h`, `fileprocess.cpp`)
+- **Status**: Only used when `ENABLE_GRPC` is defined, but it's never set
+- **Dependencies**: gRPC libraries, protobuf
+- **Action**: Remove both files
+
+#### Message Queue Worker (`mq_worker.h`, `mq_worker.cpp`)
+- **Status**: Only used when `USE_PULSAR` is defined, but it's never set
+- **Dependencies**: Pulsar client library, JSON library
+- **Action**: Remove both files
+
+### 3. **Unused Python Files**
+
+#### `worker.py`
+- **Status**: Pulsar-based worker that's never used
+- **Dependencies**: Pulsar client, subprocess calls to `./qrtool`
+- **Action**: Remove file
+
+#### `server.py`
+- **Status**: Flask server with hardcoded credentials, never called
+- **Dependencies**: Flask, subprocess calls to `./qrtool`
+- **Action**: Remove file
+
+### 4. **Unused Functions in `libqr.cpp`**
+
+```cpp
+// Remove these unused functions:
+double emblem_roi_similarity(SimilarityAlg alg, InputArray std_in, InputArray frame_roi_in, string &err)  // Lines ~444-488
+static inline void showimg_(const char *title, Mat &img)  // Lines ~48-50
+#define show(img) showimg_(#img, img)  // Line ~51
+```
+
+**Impact**: Removes unused ROI similarity comparison and image display utilities.
+
+### 5. **Unused Header Files**
+
+#### `string_format.h`
+- **Status**: Only used once in `libqr.cpp` for one error message
+- **Usage**: `err = string_format("image too blurry: %lf < %lf", sharpness, thres);`
+- **Action**: Consider inlining the single usage or removing if not critical
+
+## 🔧 **Build System Cleanup**
+
+### Makefile Simplification
+
+Remove unused conditional builds:
+
+```makefile
+# Remove these unused variables and their usage:
+USE_PULSAR :=                    # Line 19
+ENABLE_GRPC :=                  # Line 21
+
+# Remove conditional compilation:
+$(if $(USE_PULSAR), mq_worker.cpp) \           # Line 37
+$(if $(ENABLE_GRPC), fileprocess.o fileprocess.pb.o fileprocess.grpc.pb.o) \  # Line 38
+$(if $(USE_PULSAR), -lpulsar) \                # Line 46
+
+# Remove unused targets:
+fileprocess.o: fileprocess.grpc.pb.h           # Line 58
+```
+
+## 📊 **Current Usage Analysis**
+
+### **Actually Used (Keep)**
+- `qrtool.cpp` - Main executable (only `angle_cmd` is used)
+- `qrtool_wasm.cpp` - WebAssembly version for web/scanner
+- `libqr.cpp` - Core QR processing logic
+- `base64.cpp` - Used by mq_worker (but mq_worker itself is unused)
+- `string_format.h` - Used once in libqr.cpp
+
+### **Build Targets (Keep)**
+- `qrtool` - Main binary
+- `qrtool.web.js` - Web version
+- `qrtool.wx.js` - WeChat mini-program version
+- `qrtool.wx.wasm.br` - Compressed WASM for WeChat
+
+## 🚀 **Implementation Steps**
+
+1. **Phase 1: Remove Unused Functions**
+   - Remove `detect_cmd`, `dot_cmd`, `roi_verify_cmd` from `qrtool.cpp`
+   - Remove `emblem_roi_similarity`, `showimg_`, `show` from `libqr.cpp`
+
+2. **Phase 2: Remove Unused Infrastructure**
+   - Remove `http.h`, `http.cc`
+   - Remove `fileprocess.h`, `fileprocess.cpp`
+   - Remove `mq_worker.h`, `mq_worker.cpp`
+
+3. **Phase 3: Remove Unused Python Files**
+   - Remove `worker.py`
+   - Remove `server.py`
+
+4. **Phase 4: Clean Build System**
+   - Simplify Makefile by removing unused conditionals
+   - Remove unused dependencies and linking
+
+5. **Phase 5: Test and Verify**
+   - Ensure `qrtool` still builds and works
+   - Verify WASM builds still function
+   - Test core QR angle detection functionality
+
+## 📈 **Expected Benefits**
+
+- **Reduced binary size**: Remove unused command functions
+- **Simplified build**: Remove unused conditional compilation
+- **Cleaner codebase**: Remove dead infrastructure code
+- **Faster builds**: Fewer dependencies and compilation steps
+- **Easier maintenance**: Less code to maintain and debug
+
+## ⚠️ **Risks and Considerations**
+
+- **Dependencies**: Some files may have hidden dependencies
+- **Build testing**: Need to verify all build targets still work
+- **Functionality**: Ensure core QR processing isn't affected
+- **Documentation**: Update any documentation that references removed code
+
+## 📝 **Progress Tracking**
+
+- [ ] Phase 1: Remove unused functions
+- [ ] Phase 2: Remove unused infrastructure  
+- [ ] Phase 3: Remove unused Python files
+- [ ] Phase 4: Clean build system
+- [ ] Phase 5: Test and verify
+- [ ] Update documentation
+
+---
+
+**Last Updated**: $(date)
+**Status**: Planning Phase
+**Assignee**: TBD