Refactor code structure for improved readability and maintainability

Author: jsonify

.github/LOCKFILE_NOTE.md

@@ -0,0 +1,27 @@
+# About pnpm-lock.yaml
+
+This file **MUST be committed** to the repository for:
+
+1. **Reproducible builds** - Ensures everyone gets the same dependency versions
+2. **CI/CD** - GitHub Actions needs this file to install dependencies with `--frozen-lockfile`
+3. **Security** - Prevents dependency drift and supply chain attacks
+
+## Common Issues
+
+### "Cannot install with frozen-lockfile because pnpm-lock.yaml is absent"
+
+**Cause**: The lockfile is in `.gitignore` or wasn't committed
+
+**Solution**:
+1. Remove `pnpm-lock.yaml` from `.gitignore`
+2. Run `git add pnpm-lock.yaml`
+3. Commit and push
+
+### When to regenerate the lockfile
+
+Only regenerate when you:
+- Add/remove dependencies
+- Update dependency versions
+- Run `pnpm update`
+
+**Command**: `pnpm install` will update the lockfile automatically

.gitignore

@@ -17,5 +17,4 @@ node_modules/
 Thumbs.db
 
 # pnpm
-pnpm-lock.yaml
 .pnpm-debug.log*

AUTOMATED_TESTING.md

@@ -186,3 +186,28 @@ If all these pass locally, they should pass in CI.
 - Don't specify `version:` in the pnpm/action-setup step when `packageManager` is set in package.json
 - The action automatically reads the version from the `packageManager` field
 - Our workflows use pnpm@10.18.0 from package.json
+
+### "Cannot install with frozen-lockfile because pnpm-lock.yaml is absent"
+
+**Cause**: The `pnpm-lock.yaml` file is missing from the repository (was in `.gitignore`)
+
+**Solution**:
+```bash
+# 1. Remove pnpm-lock.yaml from .gitignore (if present)
+# 2. Add the lockfile to git
+git add pnpm-lock.yaml
+
+# 3. Commit it
+git commit -m "chore: add pnpm-lock.yaml for reproducible builds"
+
+# 4. Push
+git push
+```
+
+**Why this is important**:
+- Ensures reproducible builds across all environments
+- Required for CI/CD with `--frozen-lockfile` flag
+- Prevents dependency drift and security issues
+- Standard practice for all package managers (npm, yarn, pnpm)
+
+**Note**: The `pnpm-lock.yaml` file should **always** be committed to version control, never ignored.