| name | ShareX Architecture and Porting |
| description | Platform abstraction rules, porting guidelines, and architecture standards for XerahS |
Platform Abstractions and Native Code Rules
All platform specific functionality must be isolated behind platform abstraction interfaces.
No code outside XerahS.Platform.* projects may reference:
- NativeMethods
- NativeConstants, NativeEnums, NativeStructs
- Win32 P/Invoke
- System.Windows.Forms
- Windows specific handles or messages
Direct calls to Windows APIs are forbidden in Common, Core, Uploaders, Media, or other backend projects.
Required Architecture
Define platform neutral interfaces in XerahS.Platform.Abstractions.
Implement Windows functionality in XerahS.Platform.Windows.
Create stub implementations for future platforms:
- XerahS.Platform.Linux
- XerahS.Platform.MacOS
Windows-Only Features
If a capability is Windows only:
- It must still be defined via an abstraction interface.
- Windows provides the concrete implementation.
- Other platforms provide a stub implementation that either:
- throws PlatformNotSupportedException, or
- returns a safe no-op with a logged warning.
UI and workflows must detect capability availability and disable or hide unsupported features.
Porting Rule for Existing ShareX Code
A file may only be ported directly if it contains zero references to:
- NativeMethods or related native helpers
- WinForms types
- Windows specific interop
If a file mixes logic and native calls:
- Extract pure logic into Common or Core.
- Move native code into XerahS.Platform.Windows.
- Replace callsites with interface calls.
Native method names and signatures should remain Windows specific and must not leak into shared layers.
Enforcement
When porting ShareX.HelpersLib, files that reference:
- NativeMethods.cs
- NativeMethods_Helpers.cs
- NativeMessagingHost.cs
- DWM, hooks, clipboard, or input APIs
must be treated as platform code and cannot be copied wholesale.
Main Goal and Porting Rules
- Main goal: build XerahS by porting the ShareX backend first, then designing the Avalonia UI.
- Examine
C:\Users\liveu\source\repos\ShareX Team\ShareX to understand existing non-UI logic and reuse it by copying into this repo after the Avalonia solution and projects are drafted.
- Do not reuse WinForms or any WinForms UI code; only copy non-UI methods and data models.
- Keep the backend port the priority until the UI design phase is explicitly started.
Avalonia Solution Proposal (from ShareX analysis)
- Start with the simplest backend libraries first, then move to more complex modules.
- Proposed structure:
XerahS.Common: shared helpers, serialization, utilities.XerahS.Core: task settings, workflows, application-level services.XerahS.Uploaders: uploaders, config, OAuth, HTTP helpers.XerahS.History: history models and persistence.XerahS.Indexer: file indexing and search.XerahS.ImageEffects: filters/effects pipeline.XerahS.Media: encoding, thumbnails, FFmpeg integration.XerahS.ScreenCapture: capture engines and platform abstractions.XerahS.Platform.*: OS-specific implementations (Windows first, others later).XerahS.App and XerahS.UI: Avalonia UI and view models (defer until backend is ready).
Historical Comparisons and Parity
When asked to ensure feature parity with a specific historical commit or "make it identical to commit X":
- Do not rely on repeated git calls: Avoid repeatedly querying git history for file contents during the session.
- Create a
ref directory: Create a temporary folder (e.g., src/XerahS/ref).
- Download reference files: Use
git show <commit_hash>:<file_path> > src/XerahS/ref/<commit_short>_<filename> to verify the state of relevant files at that commit.
- Compare locally: Perform diffs and analysis between the local current files and the downloaded reference files.
- Clean up: Remove the
ref directory once the task is complete and verified, unless instructed otherwise.
This reduces git command overhead and provides a stable reference point for parity checks.
