Problem statement
The current implementation of case management and result tracking relies on uncoordinated, non-atomic filesystem operations. Specifically, DataFileClass.py utilizes a Read-Modify-Write pattern for global state files like view/resData.json.
As the project scales toward Async Execution (#186) and UUID Isolation (#191), the risk of data corruption significantly increases. Without filesystem-level atomicity:
-Concurrent Writes: Simultaneous requests to /createCaseRun or /updateCaseRun can lead to permanent data loss where one user's case metadata is overwritten by another's.
-JSON Corruption: A system crash or process interrupt during File.writeFile (which performs a direct write) can leave a partially written, unparseable JSON file, triggering non-deterministic 500 errors.
-Windows-Specific Failures: Concurrent attempts to open the same file descriptor will trigger PermissionError in the current un-locked environment.
Proposed solution
I propose a standalone Stability Utility—API/Utils/AtomicIO.py—that decouples business logic from disk I/O safety.
-Atomic Replacement Pattern: Implement save_json_atomic(path, data). It will write to a .tmp file and then use os.replace() to finalize. This ensures the target file is either fully updated or unchanged, never corrupted.
-Advisory File Locking: Introduce a lightweight locking mechanism for shared metadata files. This ensures that even in an Async environment, only one process can mutate resData.json at a time.
-Decoupled Implementation: By placing this in a Utility class, we avoid merge conflicts with the active logic changes in #186 and #191 while providing those PRs with the safety primitives they need.
Acceptance criteria
-[ ] Zero-Corruption Guarantee: Unit tests must prove that an interrupted write does not destroy the original JSON file.
-[ ] Concurrency Verification: A stress test demonstrating 10 simultaneous /createCaseRun requests correctly appends all 10 cases without data loss.
-[ ] Track Alignment: Measurably reduces "FileSystem" related 500 errors in the datafileroute.py exception handlers.
-[ ] Architecture Update: Migration of DataFileClass.py methods (createCaseRun, updateCaseRun, deleteScenarioCaseRuns) to use the new atomic utility.
Dependencies and constraints
-Independent Utility: This is a standalone "Safety Layer" and I made sure that it doesn't depend on any unmerged features.
-Research-First Audit: I have identified specific vulnerabilities in DataFileClass.py and datafileroute.py that are not addressed by current PRs (#191, #186).
-No API Changes: This improvement is purely internal and does not change any frontend-to-backend API contracts.
Problem statement
The current implementation of case management and result tracking relies on uncoordinated, non-atomic filesystem operations. Specifically, DataFileClass.py utilizes a Read-Modify-Write pattern for global state files like view/resData.json.
As the project scales toward Async Execution (#186) and UUID Isolation (#191), the risk of data corruption significantly increases. Without filesystem-level atomicity:
-Concurrent Writes: Simultaneous requests to /createCaseRun or /updateCaseRun can lead to permanent data loss where one user's case metadata is overwritten by another's.
-JSON Corruption: A system crash or process interrupt during File.writeFile (which performs a direct write) can leave a partially written, unparseable JSON file, triggering non-deterministic 500 errors.
-Windows-Specific Failures: Concurrent attempts to open the same file descriptor will trigger PermissionError in the current un-locked environment.
Proposed solution
I propose a standalone Stability Utility—API/Utils/AtomicIO.py—that decouples business logic from disk I/O safety.
-Atomic Replacement Pattern: Implement save_json_atomic(path, data). It will write to a .tmp file and then use os.replace() to finalize. This ensures the target file is either fully updated or unchanged, never corrupted.
-Advisory File Locking: Introduce a lightweight locking mechanism for shared metadata files. This ensures that even in an Async environment, only one process can mutate resData.json at a time.
-Decoupled Implementation: By placing this in a Utility class, we avoid merge conflicts with the active logic changes in #186 and #191 while providing those PRs with the safety primitives they need.
Acceptance criteria
-[ ] Zero-Corruption Guarantee: Unit tests must prove that an interrupted write does not destroy the original JSON file.
-[ ] Concurrency Verification: A stress test demonstrating 10 simultaneous /createCaseRun requests correctly appends all 10 cases without data loss.
-[ ] Track Alignment: Measurably reduces "FileSystem" related 500 errors in the datafileroute.py exception handlers.
-[ ] Architecture Update: Migration of DataFileClass.py methods (createCaseRun, updateCaseRun, deleteScenarioCaseRuns) to use the new atomic utility.
Dependencies and constraints
-Independent Utility: This is a standalone "Safety Layer" and I made sure that it doesn't depend on any unmerged features.
-Research-First Audit: I have identified specific vulnerabilities in DataFileClass.py and datafileroute.py that are not addressed by current PRs (#191, #186).
-No API Changes: This improvement is purely internal and does not change any frontend-to-backend API contracts.