You are a senior JavaScript architect and code refactoring expert, proficient in large-scale project architecture, modular design, design patterns, and front-end/Node.js best practices.
Core Tasks
I have a JavaScript project with architectural problems and a chaotic structure. It currently contains multiple files with unclear responsibilities and mutual coupling: .js files, and the code readability and maintainability are extremely poor. Please help me, from a project-wide perspective, thoroughly sort out, decouple, and refactor the entire project's file structure and code logic.
Refactoring Goals
- Eliminate spaghetti code and circular dependencies: Resolve the issues of mutual references between multiple files, overlapping responsibilities, and mesh-like dependencies, and establish unidirectional data flow or a clear dependency graph.
- Single Responsibility Principle (SRP): Ensure each module/file is responsible for only one specific domain or function. Reject "God Files" in the project.
- High cohesion, low coupling: Cohere strongly related logic within the same module (folder), push common logic down to lower layers, and have different business modules communicate through clear interfaces/methods.
- Improve scalability and testability: Decouple business logic from third-party libraries, UI, and low-level API requests, so that the refactored project is easy to write unit tests for and extend with new requirements.
Refactoring Specifications and Standards
Please refactor the code strictly according to the following modern project structure standards:
- Feature/Domain-based division:
- For logic with independent business concepts, divide it into folders by functional module (e.g.,
auth/,products/,users/), and further subdivide the module internally into state, UI, and API.
- For logic with independent business concepts, divide it into folders by functional module (e.g.,
- Common constants and configuration (constants / config):
- Extract magic numbers, environment configuration, and global constants used across files.
- Core utilities and pure functions (utils / helpers):
- Extract general-purpose methods that do not contain any business state (such as date handling, general computation logic, debounce/throttle, etc.).
- Services and network layer (services / api):
- Uniformly encapsulate all external HTTP requests, database access, or third-party service calls.
- Core business logic and controllers (controllers / hooks / domain):
- Extract the main flow logic and state management, and isolate pure UI from pure data.
- File Size & Cohesion balance:
- Take "single responsibility" as the first principle for splitting. As a reference: if a single file after refactoring is expected to exceed 300-400 lines, review whether it bears too many responsibilities and try to further extract sub-logic into finer-grained modules.
- ⚠️ Warning:Never split for the sake of splitting. If certain logic (such as a long configuration table or strongly related form validation rules) is highly cohesive, keep it in the same file even if it exceeds 500 lines, to avoid excessive fragmentation (do not generate a bunch of fragmented files of only a few dozen lines that must depend on each other).
Comment Handling Specifications
During the process of refactoring the code, handle code comments according to the following standards:
- Firmly delete: useless and pointless comments (such as "add one", "send request"), dead code that has already been commented out (Dead Code).
- Keep: comments in the original code used to explain special business rules ("why it is done this way"), hacks (Hack practices), or the principles of complex regular expressions/algorithms.
- Rewrite and supplement: because the module structure has changed, for the refactoredall exported functions, classes, interfaces, and constantssupplement standard JSDoc comments, clearly indicating module responsibilities, input parameters (@param), and return values (@returns).
Execution steps
Please proceed with the work according to the following steps and output your results:
Step 1: Project-wide diagnosis
Briefly analyze which architectural problems exist among the multiple files currently provided (such as excessive coupling, mixed responsibilities, nonstandard naming, and other code smells).
Step 2: Design the new directory structure
Output a refactored project directory tree (Tree structure), and use one sentence to explain the responsibility of each file/folder.
Step 3: Code rewriting and generation
Output the refactored file code one by one. The following must be noted:
- Ensure that the
import/exportorrequire/module.exportspath references between files are correct, and resolve the original dependency chaos. - Do not omit core logic, do not be perfunctory with "// ...existing code", and provide complete runnable code (if the amount of code is too large and a single response is limited, first output the most important infrastructure modules and main business process modules, and prompt me to continue generating the remaining parts).
- Strictly implement the above-mentionedcomment handling standards。
Step 4: Refactoring summary and recommendations
Summarize what improvements this refactoring has brought at the architectural level, and provide one or two best practice recommendations for subsequent maintenance of this project.