Backend Architecture Refactoring (#6094)

[dinhlongviolin1]

Describe Your Changes

Previous Implementation

The existing codebase structure, while functional, presented several opportunities for improvement to enhance maintainability and developer experience:

• Monolithic command structure: All Tauri commands were centralized in a single cmd.rs file, making it challenging to navigate and understand the scope of individual features
• Mixed responsibilities: Hardware management, LLM server operations, and utility functions were tightly coupled within the core module, making it difficult to isolate and test individual components
• Inline utility functions: Common utilities were scattered throughout the codebase rather than being organized in a reusable manner
• Limited modularity: The architecture made it challenging for new contributors to understand the boundaries between different system components

Implemented Changes

This refactoring introduces a more modular and maintainable architecture through the following improvements:

1. Plugin-based architecture: Separated concerns into two dedicated Tauri plugins:

   • tauri-plugin-hardware: Handles all hardware-related operations (system info, GPU detection, resource monitoring)
   • tauri-plugin-llamacpp: Manages LLM server lifecycle, model loading, and session management

   Rationale: This separation allows for independent development, testing, and versioning of each component while reducing coupling between unrelated features.

2. Centralized utilities: Created a dedicated utils crate containing common functionality:

   • Organized utilities by type (cli, config, crypto, fs, http, math, network, path, string, system)
   • Reusable across all modules and plugins

   Rationale: Eliminates code duplication and provides a single source of truth for common operations, improving consistency and reducing maintenance burden.

3. Feature-based organization: Restructured the src directory to organize code by feature domain:

   • Each feature (app, downloads, extensions, filesystem, mcp, server, system, threads) now has its own module with dedicated commands, helpers, models, and tests
   • Clear separation of concerns with standardized module structure

   Rationale: This structure provides better code discoverability and makes it immediately clear where to find or add functionality for specific features.

Next Steps

1. Documentation: Add comprehensive documentation for the new folder structure, including architectural documentation and contribution guidelines to help onboard new developers

2. Frontend refactoring: Apply similar modular principles to the frontend codebase to maintain consistency across the entire application stack

3. API wrapper implementation: Use Tauri plugin API wrapper instead of invoking rust backend function directly on the frontend side

Fixes Issues

• Related to epic: Jan code base restructuring #6094

Self Checklist

• Added relevant comments, esp in complex areas
• Updated docs (for bug fixes / features)
• Created issues for follow-up changes or refactoring needed

---

Important

Refactors backend architecture to a plugin-based system, centralizes utilities, and organizes code by feature domain for improved modularity and maintainability.

• Architecture:
  • Introduces plugin-based architecture with tauri-plugin-hardware and tauri-plugin-llamacpp.
  • Centralizes utilities into a utils crate.
  • Organizes src directory by feature domain (e.g., app, downloads, extensions).
• Commands:
  • Moves Tauri commands from cmd.rs to feature-specific modules.
  • Updates command invocations to use new plugin paths (e.g., plugin:hardware|get_system_info).
• Plugins:
  • tauri-plugin-hardware handles hardware operations.
  • tauri-plugin-llamacpp manages LLM server lifecycle.
• Misc:
  • Adds yarn build:tauri:plugin:api to Makefile and package.json.
  • Updates Cargo.toml and Cargo.lock for new dependencies.
  • Refactors tests and helper functions to align with new architecture.

^{This description was created by for 0edc339. You can customize this summary. It will automatically update as commits are pushed.}

[github-actions]

Barecheck - Code coverage report

Total: 28.7%

Your code coverage diff: 0.00% ▴

✅ All code changes are covered

[ellipsis-dev]

Caution

Changes requested ❌

Reviewed everything up to aa26e17 in 3 minutes and 49 seconds. Click for details.

• Reviewed 17073 lines of code in 108 files
• Skipped 3 files when reviewing.
• Skipped posting 7 draft comments. View those below.
• Modify your settings and rules to customize what types of comments Ellipsis leaves. And don't forget to react with 👍 or 👎 to teach Ellipsis.

1. src-tauri/plugins/tauri-plugin-hardware/permissions/schemas/schema.json:94

• Draft comment:
  Typo suggestion: In the 'Permission' description, consider changing "fine grain control" to "fine‐grained control" for improved clarity.
• Reason this comment was not posted:
  Decided after close inspection that this draft comment was likely wrong and/or not actionable: usefulness confidence = 0% vs. threshold = 50% This is a new file being added, so the comment is about changed code. However, this is a very minor grammatical suggestion that doesn't affect functionality. The current form "fine grain control" is understandable, and there's inconsistency in the file since "fine grained" is used without a hyphen elsewhere. Making this change would actually introduce inconsistency. The comment does point out a legitimate grammatical improvement - "fine-grained" is technically more correct than "fine grain" when used as an adjective. While technically correct, this is an extremely minor issue that doesn't affect understanding. The rules state not to make purely informative comments or obvious/unimportant suggestions. Delete this comment as it's too minor and would introduce inconsistency with other usage in the file.

2. src-tauri/plugins/tauri-plugin-llamacpp/permissions/schemas/schema.json:94

• Draft comment:
  Typo: In the "Permission" description, consider changing "fine grain control" to "fine-grained control" to improve clarity.
• Reason this comment was not posted:
  Decided after close inspection that this draft comment was likely wrong and/or not actionable: usefulness confidence = 10% vs. threshold = 50% While technically correct that "fine-grained" is the more proper form with a hyphen, this is a minor grammatical issue in a documentation string. The meaning is perfectly clear either way. The codebase itself is inconsistent, using both forms. This kind of minor grammatical nitpick doesn't warrant a PR comment. The hyphenated form is technically more correct according to style guides. Consistency in documentation can be important for professionalism. While technically correct, this level of grammatical nitpicking creates noise in PR reviews and doesn't materially improve the code or documentation quality. Delete this comment as it's too minor of a grammatical issue to warrant discussion in a PR review.

3. src-tauri/src/core/filesystem/commands.rs:113

• Draft comment:
  Inconsistent naming in error message: The function is named readdir_sync but the error message reads "read_dir_sync error: Invalid argument". It might be clearer to align the message with the function name.
• Reason this comment was not posted:
  Decided after close inspection that this draft comment was likely wrong and/or not actionable: usefulness confidence = 20% vs. threshold = 50% While technically correct, this is a very minor inconsistency in an error message that would only be seen in edge cases. The code is also marked as deprecated in the file header comments. The inconsistency doesn't affect functionality and the message is still clear enough to understand. The inconsistency could cause confusion for developers maintaining the code, and consistency in error messages is a good practice. Given that this code is explicitly marked as deprecated and will be removed soon, fixing minor cosmetic issues in error messages provides little value. While technically correct, this comment addresses a very minor cosmetic issue in soon-to-be-deprecated code. The comment should be removed as it doesn't provide enough value.

4. src-tauri/src/lib.rs:38

• Draft comment:
  Typo in the comment: "Deperecate soon" should be "Deprecate soon".
• Reason this comment was not posted:
  Comment was on unchanged code.

5. src-tauri/utils/src/network.rs:41

• Draft comment:
  Typo suggestion: In the error message "Failed to find an available port for the model to load", the word "model" might be a typo. Consider verifying if this should be "module" or another term to more accurately reflect the intended context.
• Reason this comment was not posted:
  Decided after close inspection that this draft comment was likely wrong and/or not actionable: usefulness confidence = 20% vs. threshold = 50% Without more context about how this function is used, we can't know if "model" is actually incorrect. The function could be specifically designed for allocating ports for ML models or other model-related services. The word "model" might be intentional and correct. Making assumptions about the intended usage without full context would be speculative. I might be too cautious - if this is truly a generic utility function, "module" would be more appropriate than the specific term "model". Even if "module" might be more generic, we don't have enough context to be certain that "model" is wrong. The function could be intentionally designed for model-related services. The comment should be deleted because it makes assumptions about intended usage without sufficient context to know if "model" is actually incorrect.

6. src-tauri/utils/src/network.rs:137

• Draft comment:
  Minor typographical note: In the comment "Converts HashMap<String,String> to reqwest HeaderMap", consider adding a space after the comma (i.e., "HashMap<String, String>") for consistency and clarity.
• Reason this comment was not posted:
  Decided after close inspection that this draft comment was likely wrong and/or not actionable: usefulness confidence = 10% vs. threshold = 50% This is an extremely minor formatting suggestion that doesn't affect functionality. The actual function signature already has the correct spacing. The rules state not to make purely informative comments or comments that are obvious/unimportant. This seems to fall into that category. The comment is technically correct and would improve consistency between the doc comment and the actual code. Documentation quality is important. While documentation quality matters, this is too minor of an issue to warrant a PR comment. It's purely cosmetic and doesn't affect understanding. Delete the comment as it's too minor and purely stylistic, violating the rule about not making obvious or unimportant comments.

7. src-tauri/utils/src/system.rs:37

• Draft comment:
  Typo: The raw string literal on this line appears to be malformed. The literal r"\?" ends with a backslash, which is not allowed in Rust raw string literals. Consider using a regular string literal with proper escaping (e.g. "\\?\") or adjusting the raw string delimiter (e.g. r#"\?"#) to correctly represent the UNC prefix.
• Reason this comment was not posted:
  Decided after close inspection that this draft comment was likely wrong and/or not actionable: usefulness confidence = 10% vs. threshold = 50% The comment appears to be incorrect. In Rust, r"\?" is actually valid syntax for a raw string literal. The backslash at the end is not escaping anything - it's just a literal backslash character. This is commonly used for Windows paths. The code is trying to trim a Windows UNC path prefix, and the current syntax is correct for that purpose. Could there be platform-specific behavior I'm not considering? Maybe there's a reason they suggested the alternative syntax. No, the current syntax r"\?" is the standard way to represent this Windows path prefix in Rust. The suggested alternatives would actually make the code more complex without any benefit. The comment should be deleted as it incorrectly claims there's a syntax error when the code is actually correct.

Workflow ID: wflow_mn73Ut1iiWPCgOBn

^{You can customize by changing your verbosity settings, reacting with 👍 or 👎, replying to comments, or adding code review rules.}

[ellipsis-dev]

Important

Looks good to me! 👍

Reviewed ef080b8 in 2 minutes and 13 seconds. Click for details.

• Reviewed 119 lines of code in 4 files
• Skipped 0 files when reviewing.
• Skipped posting 3 draft comments. View those below.
• Modify your settings and rules to customize what types of comments Ellipsis leaves. And don't forget to react with 👍 or 👎 to teach Ellipsis.

1. src-tauri/Cargo.toml:1

• Draft comment:
  Main Cargo.toml is well-structured. The use of resolver version 2, clear feature definitions, and target-specific dependencies is excellent. Good job on organization!
• Reason this comment was not posted:
  Confidence changes required: 0% <= threshold 50% None

2. src-tauri/plugins/tauri-plugin-hardware/Cargo.toml:1

• Draft comment:
  The hardware plugin's Cargo.toml provides clear metadata and proper exclusion of unnecessary directories. The 'links' field is correctly used. Ensure dependency versions (e.g. for libc) remain compatible with the main crate.
• Reason this comment was not posted:
  Confidence changes required: 0% <= threshold 50% None

3. src-tauri/plugins/tauri-plugin-llamacpp/Cargo.toml:1

• Draft comment:
  The LlamaCpp plugin Cargo.toml is consistent with the main project versioning. The relative path for jan-utils is correctly specified, and target-specific dependencies for Windows and Unix are well defined.
• Reason this comment was not posted:
  Confidence changes required: 0% <= threshold 50% None

Workflow ID: wflow_U0sSrcIFpnsQH9v6

^{You can customize by changing your verbosity settings, reacting with 👍 or 👎, replying to comments, or adding code review rules.}

[ellipsis-dev]

Skipped PR review on 2dc0993 because no changed files had a supported extension. If you think this was in error, please contact us and we'll fix it right away.

[ellipsis-dev]

Skipped PR review on 3594ea8 because no changed files had a supported extension. If you think this was in error, please contact us and we'll fix it right away.

[ellipsis-dev]

Skipped PR review on dea58fa because no changed files had a supported extension. If you think this was in error, please contact us and we'll fix it right away.

[ellipsis-dev]

Important

Looks good to me! 👍

Reviewed de43489 in 3 minutes and 21 seconds. Click for details.

• Reviewed 1271 lines of code in 35 files
• Skipped 1 files when reviewing.
• Skipped posting 5 draft comments. View those below.
• Modify your settings and rules to customize what types of comments Ellipsis leaves. And don't forget to react with 👍 or 👎 to teach Ellipsis.

1. src-tauri/plugins/tauri-plugin-hardware/guest-js/index.ts:49

• Draft comment:
  Add a trailing newline at the end of the file for POSIX compatibility.
• Reason this comment was not posted:
  Confidence changes required: 33% <= threshold 50% None

2. src-tauri/src/core/server/commands.rs:28

• Draft comment:
  The trusted_hosts argument is wrapped in a Vec (using vec![trusted_hosts]), which creates a nested Vec (Vec<Vec>) if trusted_hosts is already a Vec. Confirm if this nesting is intentional.
• Reason this comment was not posted:
  Comment was not on a location in the diff, so it can't be submitted as a review comment.

3. src-tauri/src/core/mcp/helpers.rs:527

• Draft comment:
  Using '()' to call .serve(process) is unclear. Consider using a more descriptive constructor or helper for initializing the RunningService to improve code clarity.
• Reason this comment was not posted:
  Comment was not on a location in the diff, so it can't be submitted as a review comment.

4. src-tauri/src/lib.rs:147

• Draft comment:
  Using blocking calls (tokio::task::block_in_place and block_on) during the Exit event may delay shutdown or cause potential deadlocks. Consider using a fully asynchronous cleanup approach if possible.
• Reason this comment was not posted:
  Comment was not on a location in the diff, so it can't be submitted as a review comment.

5. src-tauri/plugins/tauri-plugin-hardware/permissions/autogenerated/reference.md:1

• Draft comment:
  There is a slight inconsistency in the use of singular and plural forms. The header on line 1 is "## Default Permission" (singular), but the description on line 3 refers to "Default permissions" (plural). Consider updating one for consistency.
• Reason this comment was not posted:
  Decided after close inspection that this draft comment was likely wrong and/or not actionable: usefulness confidence = 10% vs. threshold = 50% While the inconsistency is real, this is a very minor documentation issue. The meaning is perfectly clear either way. The rules state not to make comments that are obvious or unimportant. This seems like a nitpick that doesn't materially improve code quality or functionality. The inconsistency could potentially confuse users about whether they're dealing with a single permission or multiple permissions. Documentation accuracy is important for user understanding. While documentation accuracy matters, this particular inconsistency is extremely minor and unlikely to cause any real confusion given the clear list of permissions that follows. This comment should be deleted as it violates the rule about not making obvious or unimportant comments. The inconsistency is too minor to warrant a PR comment.

Workflow ID: wflow_lA8ytUxF76wx0tEm

^{You can customize by changing your verbosity settings, reacting with 👍 or 👎, replying to comments, or adding code review rules.}

[ellipsis-dev]

Caution

Changes requested ❌

Reviewed fa3234a in 4 minutes and 13 seconds. Click for details.

• Reviewed 315 lines of code in 15 files
• Skipped 0 files when reviewing.
• Skipped posting 6 draft comments. View those below.
• Modify your settings and rules to customize what types of comments Ellipsis leaves. And don't forget to react with 👍 or 👎 to teach Ellipsis.

1. Makefile:29

• Draft comment:
  Ensure the new 'yarn build:tauri:plugin:api' command is defined in package.json and reliably runs in all environments (CI and local).
• Reason this comment was not posted:
  Comment did not seem useful. Confidence is useful = 0% <= threshold 50% The comment is asking the PR author to ensure that a command is defined and works in all environments. This falls under the rule of not asking the author to ensure or verify things, which is not allowed.

2. README.md:122

• Draft comment:
  Update documentation to reflect the new build step for Tauri plugin APIs; ensure all contributors follow this updated process.
• Reason this comment was not posted:
  Comment did not seem useful. Confidence is useful = 0% <= threshold 50% This comment is asking the PR author to update documentation and ensure that all contributors follow a new process. It is not making a specific code suggestion or pointing out a potential issue with the code itself. It seems to be more of a process-related comment, which is not allowed according to the rules.

3. extensions/llamacpp-extension/package.json:31

• Draft comment:
  Using 'link:' for plugin dependencies is acceptable; verify that the relative paths remain stable as the project evolves.
• Reason this comment was not posted:
  Confidence changes required: 50% <= threshold 50% None

4. extensions/llamacpp-extension/src/backend.ts:125

• Draft comment:
  Usage of the global 'IS_WINDOWS' constant may lead to runtime issues if not defined; consider importing or defining it explicitly.
• Reason this comment was not posted:
  Comment was not on a location in the diff, so it can't be submitted as a review comment.

5. extensions/llamacpp-extension/src/backend.ts:233

• Draft comment:
  Refactoring to call getSystemInfo directly improves modularity; however, ensure all tests mock the correct module. Also, verify that 'compareVersions' robustly handles version strings of varying lengths.
• Reason this comment was not posted:
  Comment did not seem useful. Confidence is useful = 50% <= threshold 50% The comment suggests a refactoring for improved modularity, which is a valid code suggestion. However, it also asks the author to ensure tests mock the correct module and verify the robustness of 'compareVersions', which violates the rule against asking the author to ensure or verify things. The first part of the comment is useful, but the latter part is not allowed.

6. web-app/src/lib/service.ts:41

• Draft comment:
  The regex-based conversion of route names to snake_case may produce unexpected results for acronyms or multiple uppercase letters; verify that this transformation meets API naming expectations.
• Reason this comment was not posted:
  Comment was not on a location in the diff, so it can't be submitted as a review comment.

Workflow ID: wflow_72SsrsGix7VoEpCv

^{You can customize by changing your verbosity settings, reacting with 👍 or 👎, replying to comments, or adding code review rules.}

[ellipsis-dev]

Important

Looks good to me! 👍

Reviewed 882ab84 in 3 minutes and 4 seconds. Click for details.

• Reviewed 77 lines of code in 7 files
• Skipped 1 files when reviewing.
• Skipped posting 7 draft comments. View those below.
• Modify your settings and rules to customize what types of comments Ellipsis leaves. And don't forget to react with 👍 or 👎 to teach Ellipsis.

1. src-tauri/plugins/tauri-plugin-hardware/guest-js/index.ts:49

• Draft comment:
  Trailing newline added at file end for POSIX compliance.
• Reason this comment was not posted:
  Comment did not seem useful. Confidence is useful = 0% <= threshold 50% This comment is purely informative, as it only states that a trailing newline was added for POSIX compliance. It does not provide any actionable feedback or suggestions for improvement.

2. src-tauri/plugins/tauri-plugin-hardware/permissions/default.toml:7

• Draft comment:
  Trailing newline added to default.toml; ensures file ends with a newline.
• Reason this comment was not posted:
  Comment was not on a location in the diff, so it can't be submitted as a review comment.

3. src-tauri/plugins/tauri-plugin-hardware/permissions/schemas/schema.json:331

• Draft comment:
  Trailing newline added to schema.json for consistency.
• Reason this comment was not posted:
  Comment was not on a location in the diff, so it can't be submitted as a review comment.

4. src-tauri/plugins/tauri-plugin-hardware/rollup.config.js:32

• Draft comment:
  Trailing newline added in rollup.config.js; improves file consistency.
• Reason this comment was not posted:
  Comment was not on a location in the diff, so it can't be submitted as a review comment.

5. src-tauri/plugins/tauri-plugin-llamacpp/guest-js/index.ts:94

• Draft comment:
  Trailing newline added at file end in the llamacpp guest JS module.
• Reason this comment was not posted:
  Comment was not on a location in the diff, so it can't be submitted as a review comment.

6. src-tauri/plugins/tauri-plugin-llamacpp/permissions/schemas/schema.json:451

• Draft comment:
  Trailing newline added to permissions schema for consistency.
• Reason this comment was not posted:
  Comment was not on a location in the diff, so it can't be submitted as a review comment.

7. src-tauri/utils/Cargo.toml:21

• Draft comment:
  Trailing newline added to Cargo.toml to meet best practices.
• Reason this comment was not posted:
  Comment was not on a location in the diff, so it can't be submitted as a review comment.

Workflow ID: wflow_h9moFIK4mJAmzvQa

^{You can customize by changing your verbosity settings, reacting with 👍 or 👎, replying to comments, or adding code review rules.}

[ellipsis-dev]

Important

Looks good to me! 👍

Reviewed 0edc339 in 1 minute and 37 seconds. Click for details.

• Reviewed 15 lines of code in 1 files
• Skipped 0 files when reviewing.
• Skipped posting 1 draft comments. View those below.
• Modify your settings and rules to customize what types of comments Ellipsis leaves. And don't forget to react with 👍 or 👎 to teach Ellipsis.

1. extensions/llamacpp-extension/src/test/setup.ts:34

• Draft comment:
  Consider providing a default return value (or mock implementation) for getSystemInfo if your tests rely on it. This can help avoid undefined behavior in tests later on.
• Reason this comment was not posted:
  Confidence changes required: 33% <= threshold 50% None

Workflow ID: wflow_MGcdjrCLeoUthMY1

^{You can customize by changing your verbosity settings, reacting with 👍 or 👎, replying to comments, or adding code review rules.}

[louis-jan]

LGTM