# zshameel/relink architecture

> Architecture diagram of the GitHub repository zshameel/relink, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zshameel/relink
- Repository: https://github.com/zshameel/relink

## Overview

1. **What this repo is**
   Re:Link is a **Windows desktop app** built in **C#/.NET WinForms**. Its job is to act as the user’s default browser and **route clicked links to different installed browsers based on rules**. The architecture is centered around one core flow: intercept a URL click, evaluate rules, choose a browser, and launch it with that URL.

2. **Application entry and UI shell**
   `ReLinkMain.cs` is the app entry point, with `MainForm` as the main configuration/UI surface. The UI is not the product itself; it is the management console for rules, browser selection, and app behavior. `ToastForm` provides lightweight user feedback, likely for actions such as successful launches or warnings.

3. **Rule engine: URL-to-browser mapping**
   The `Rules/` folder contains the core matching logic:
   - `Rule.cs` represents a single routing rule.
   - `MatchType.cs` defines how matching works.
   - `Wildcard.cs` suggests support for pattern-based host/path matching.
   
   This subsystem is the decision layer of the app: it takes an incoming link and determines which browser should handle it.

4. **Browser abstraction and launch pipeline**
   The `Browser/` folder encapsulates everything related to browser discovery, registration, and launch:
   - `BrowserInfo.cs` and `BrowserType.cs` model available browsers.
   - `BrowserManager.cs` likely resolves the target browser and starts it.
   - `BrowserRegistrar.cs` and `BrowserRegistrarWin10.cs` indicate OS-specific default-browser registration logic.
   - `NativeHelper.cs` and `OSVersion.cs` point to Win32/OS integration needed for shell registration and compatibility handling.
   
   This is a major boundary: the app separates **rule evaluation** from **browser execution/registration**.

5. **Default-browser / link-handler integration**
   The README makes clear that Re:Link is meant to be set as the **default browser**, so the external entry point is the Windows shell’s URL handling. That means the app sits between desktop apps (email clients, chat apps, etc.) and the actual target browsers. The `BrowserRegistrar` classes likely manage this shell integration so the OS sends links to Re:Link first.

6. **Configuration and browser selector metadata**
   `Config/BrowserSelector.xml` likely stores known browser definitions or selector metadata used to populate the browser list. This is a configuration boundary separate from user-specific settings and rules. It probably helps the app understand which browsers are installed and how to refer to them consistently.

7. **User settings and persisted state**
   `Settings/BrowserSettings.cs` appears to hold user-configurable browser-related preferences. The project also includes `App.config` and `Properties/Settings.settings`, which suggests a mix of application settings and persisted user settings. This subsystem stores the user’s chosen rule mappings, defaults, and any app preferences needed across launches.

8. **Property-change infrastructure**
   `PropertyService/` provides a small internal observable model:
   - `PropertyService.cs`
   - `Properties.cs`
   - `PropertyChangedEventArgs.cs`
   
   This looks like a lightweight state/notification layer used by the WinForms UI to keep controls in sync with backing data, without introducing a full MVVM framework.

9. **Custom browser-selection UI**
   The `ImageComboBox/` folder is a reusable custom control for selecting items with icons. This is probably used in the UI wherever the user chooses a browser for a rule. It includes:
   - custom combo box rendering and dropdown behavior,
   - image handling,
   - item collections and type converters,
   - embedded bitmaps used for the control.
   
   Architecturally, this is a presentation component, not business logic.

10. **Forms and user interaction flow**
    `MainForm` is the primary configuration surface where rules are edited and browsers selected. `ToastForm` provides transient notifications. Together they form the user-facing layer, while the actual routing logic remains in `Rules/` and `Browser/`.

11. **Assets and branding**
    `Images/`, embedded bitmap resources in `ImageComboBox/`, and `Properties/Resources.*` support the UI with icons and localized/static assets. These do not affect routing logic, but they matter for the UI’s browser list and selection experience.

12. **Project boundaries and dependencies**
    `ReLink.csproj` and `ReLink.sln` show this is a single desktop application project, with `ImageComboBox` included as an internal project/component. The main architectural boundaries are:
    - **Shell integration** with Windows,
    - **Rule evaluation**,
    - **Browser launch/registration**,
    - **WinForms configuration UI**,
    - **Persistent settings/state**.

13. **How the runtime data flow likely works**
    The typical path is:
    1. Windows sends a clicked URL to Re:Link because it is the default handler.
    2. The app parses the link and consults the rule engine.
    3. The matched rule selects a browser.
    4. `BrowserManager` launches that browser with the URL.
    5. The UI reflects or allows editing of these rules and browser associations.

14. **Technology summary**
    The repo is primarily **WinForms + Windows shell integration**, with some **native/OS-specific code** for browser registration. Its architecture is intentionally small and monolithic, but internally separated into clear modules for routing, browser management, settings, and UI.

Main entry points: [`MainForm.cs`](https://github.com/zshameel/relink/blob/master/MainForm.cs) (Main form), [`Browser/BrowserManager.cs`](https://github.com/zshameel/relink/blob/master/Browser/BrowserManager.cs) (Browser manager), [`ImageComboBox/ImageComboBox.cs`](https://github.com/zshameel/relink/blob/master/ImageComboBox/ImageComboBox.cs) (Image combo), [`Browser/BrowserRegistrar.cs`](https://github.com/zshameel/relink/blob/master/Browser/BrowserRegistrar.cs) (Registrar)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_runtime["Runtime flow"]
  node_node_browserinfo["Browser info<br/>browser model<br/>[BrowserInfo.cs]"]
  node_node_browsertype{{"Browser type<br/>browser enum<br/>[BrowserType.cs]"}}
  node_node_browsermgr["Browser manager<br/>launch pipeline<br/>[BrowserManager.cs]"]
  node_node_registrar["Registrar<br/>shell integration"]
  node_node_regwin10["Win10 registrar<br/>os-specific registration"]
  node_node_native["Native helper<br/>win32 interop<br/>[NativeHelper.cs]"]
  node_node_osversion{{"OS version<br/>compatibility<br/>[OSVersion.cs]"}}
end

subgraph group_group_rules["Routing rules"]
  node_node_rule["Rule<br/>routing model<br/>[Rule.cs]"]
  node_node_matchtype{{"Match type<br/>matching enum<br/>[MatchType.cs]"}}
  node_node_wildcard["Wildcard<br/>pattern match<br/>[Wildcard.cs]"]
end

subgraph group_group_ui["WinForms UI"]
  node_node_mainform["Main form<br/>winforms shell<br/>[MainForm.cs]"]
  node_node_toast["Toast<br/>feedback form<br/>[ToastForm.cs]"]
end

subgraph group_group_state["State and settings"]
  node_node_browsersettings["Browser settings<br/>user settings<br/>[BrowserSettings.cs]"]
  node_node_propsvc["Property service<br/>state sync<br/>[PropertyService.cs]"]
  node_node_props["Properties<br/>state model<br/>[Properties.cs]"]
  node_node_propchanged["Changed args<br/>event args"]
end

subgraph group_group_presentation["UI controls"]
  node_node_imagecombo["Image combo<br/>custom control<br/>[ImageComboBox.cs]"]
  node_node_imgitem["Combo item<br/>control model"]
  node_node_imgitems["Item collection<br/>control collection"]
end

subgraph group_group_assets["Assets"]
  node_node_browselector["Browser selector<br/>config metadata"]
  node_node_resources["Resources<br/>embedded assets<br/>[Resources.resx]"]
end

subgraph group_group_bootstrap["Bootstrap"]
  node_node_entry(("App entry<br/>startup<br/>[ReLinkMain.cs]"))
end

node_node_entry -->|"starts"| node_node_mainform
node_node_mainform -->|"binds"| node_node_propsvc
node_node_mainform -->|"uses"| node_node_imagecombo
node_node_mainform -->|"edits"| node_node_browsersettings
node_node_mainform -->|"shows"| node_node_toast
node_node_rule -->|"depends on"| node_node_matchtype
node_node_rule -->|"uses"| node_node_wildcard
node_node_browsermgr -->|"selects"| node_node_browserinfo
node_node_browsermgr -->|"classifies"| node_node_browsertype
node_node_browsermgr -->|"consults"| node_node_rule
node_node_browsermgr -->|"reads"| node_node_browsersettings
node_node_registrar -->|"delegates"| node_node_regwin10
node_node_registrar -->|"calls"| node_node_native
node_node_registrar -->|"branches on"| node_node_osversion
node_node_imagecombo -->|"renders"| node_node_imgitem
node_node_imagecombo -->|"contains"| node_node_imgitems
node_node_imagecombo -->|"uses"| node_node_resources
node_node_propsvc -->|"manages"| node_node_props
node_node_propsvc -->|"raises"| node_node_propchanged
node_node_browselector -->|"describes"| node_node_browserinfo
node_node_mainform -->|"invokes"| node_node_browsermgr
node_node_toast -->|"uses"| node_node_resources
node_node_entry -->|"initializes"| node_node_registrar

click node_node_entry "https://github.com/zshameel/relink/blob/master/ReLinkMain.cs"
click node_node_mainform "https://github.com/zshameel/relink/blob/master/MainForm.cs"
click node_node_toast "https://github.com/zshameel/relink/blob/master/ToastForm.cs"
click node_node_rule "https://github.com/zshameel/relink/blob/master/Rules/Rule.cs"
click node_node_matchtype "https://github.com/zshameel/relink/blob/master/Rules/MatchType.cs"
click node_node_wildcard "https://github.com/zshameel/relink/blob/master/Rules/Wildcard.cs"
click node_node_browserinfo "https://github.com/zshameel/relink/blob/master/Browser/BrowserInfo.cs"
click node_node_browsertype "https://github.com/zshameel/relink/blob/master/Browser/BrowserType.cs"
click node_node_browsermgr "https://github.com/zshameel/relink/blob/master/Browser/BrowserManager.cs"
click node_node_registrar "https://github.com/zshameel/relink/blob/master/Browser/BrowserRegistrar.cs"
click node_node_regwin10 "https://github.com/zshameel/relink/blob/master/Browser/BrowserRegistrarWin10.cs"
click node_node_native "https://github.com/zshameel/relink/blob/master/Browser/NativeHelper.cs"
click node_node_osversion "https://github.com/zshameel/relink/blob/master/Browser/OSVersion.cs"
click node_node_browsersettings "https://github.com/zshameel/relink/blob/master/Settings/BrowserSettings.cs"
click node_node_propsvc "https://github.com/zshameel/relink/blob/master/PropertyService/PropertyService.cs"
click node_node_props "https://github.com/zshameel/relink/blob/master/PropertyService/Properties.cs"
click node_node_propchanged "https://github.com/zshameel/relink/blob/master/PropertyService/PropertyChangedEventArgs.cs"
click node_node_imagecombo "https://github.com/zshameel/relink/blob/master/ImageComboBox/ImageComboBox.cs"
click node_node_imgitem "https://github.com/zshameel/relink/blob/master/ImageComboBox/ImageComboBoxItem.cs"
click node_node_imgitems "https://github.com/zshameel/relink/blob/master/ImageComboBox/ImageComboBoxItemCollection.cs"
click node_node_browselector "https://github.com/zshameel/relink/blob/master/Config/BrowserSelector.xml"
click node_node_resources "https://github.com/zshameel/relink/blob/master/Properties/Resources.resx"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_browserinfo,node_node_browsertype,node_node_browsermgr,node_node_registrar,node_node_regwin10,node_node_native,node_node_osversion,node_node_entry toneBlue
class node_node_rule,node_node_matchtype,node_node_wildcard toneAmber
class node_node_mainform,node_node_toast toneMint
class node_node_browsersettings,node_node_propsvc,node_node_props,node_node_propchanged toneRose
class node_node_imagecombo,node_node_imgitem,node_node_imgitems toneIndigo
class node_node_browselector,node_node_resources toneTeal
```

## Components

### Runtime flow

Default-browser link interception and browser dispatch

- [Browser info](https://github.com/zshameel/relink/blob/master/Browser/BrowserInfo.cs): browser model · Describes an installed browser instance · `Browser/BrowserInfo.cs`
- [Browser type](https://github.com/zshameel/relink/blob/master/Browser/BrowserType.cs): browser enum · Identifies supported browser kinds · `Browser/BrowserType.cs`
- [Browser manager](https://github.com/zshameel/relink/blob/master/Browser/BrowserManager.cs): launch pipeline · Resolves the target browser and launches URLs · `Browser/BrowserManager.cs`
- [Registrar](https://github.com/zshameel/relink/blob/master/Browser/BrowserRegistrar.cs): shell integration · Registers Re:Link as a browser and default handler · `Browser/BrowserRegistrar.cs`
- [Win10 registrar](https://github.com/zshameel/relink/blob/master/Browser/BrowserRegistrarWin10.cs): os-specific registration · Windows 10 specific registration behavior · `Browser/BrowserRegistrarWin10.cs`
- [Native helper](https://github.com/zshameel/relink/blob/master/Browser/NativeHelper.cs): win32 interop · Native calls used by browser registration and OS integration · `Browser/NativeHelper.cs`
- [OS version](https://github.com/zshameel/relink/blob/master/Browser/OSVersion.cs): compatibility · Encodes Windows version checks and branching · `Browser/OSVersion.cs`

### Routing rules

URL matching and browser selection logic

- [Rule](https://github.com/zshameel/relink/blob/master/Rules/Rule.cs): routing model · Represents one URL-to-browser mapping rule · `Rules/Rule.cs`
- [Match type](https://github.com/zshameel/relink/blob/master/Rules/MatchType.cs): matching enum · Defines how a rule compares against a URL · `Rules/MatchType.cs`
- [Wildcard](https://github.com/zshameel/relink/blob/master/Rules/Wildcard.cs): pattern match · Pattern helper for host and path matching · `Rules/Wildcard.cs`

### WinForms UI

Configuration and feedback surfaces

- [Main form](https://github.com/zshameel/relink/blob/master/MainForm.cs): winforms shell · Primary configuration UI for rules and browser behavior · `MainForm.cs`
- [Toast](https://github.com/zshameel/relink/blob/master/ToastForm.cs): feedback form · Transient UI used to show status or warnings · `ToastForm.cs`

### State and settings

Persisted app settings and property notification

- [Browser settings](https://github.com/zshameel/relink/blob/master/Settings/BrowserSettings.cs): user settings · Stores user browser preferences and related options · `Settings/BrowserSettings.cs`
- [Property service](https://github.com/zshameel/relink/blob/master/PropertyService/PropertyService.cs): state sync · Lightweight observable state container for the UI · `PropertyService/PropertyService.cs`
- [Properties](https://github.com/zshameel/relink/blob/master/PropertyService/Properties.cs): state model · Backing property definitions used by the property service · `PropertyService/Properties.cs`
- [Changed args](https://github.com/zshameel/relink/blob/master/PropertyService/PropertyChangedEventArgs.cs): event args · Custom property-changed event arguments · `PropertyService/PropertyChangedEventArgs.cs`

### UI controls

Reusable selection control for browser picking

- [Image combo](https://github.com/zshameel/relink/blob/master/ImageComboBox/ImageComboBox.cs): custom control · Browser picker control with image-aware dropdown behavior · `ImageComboBox/ImageComboBox.cs`
- [Combo item](https://github.com/zshameel/relink/blob/master/ImageComboBox/ImageComboBoxItem.cs): control model · Selectable item used by the image combo box · `ImageComboBox/ImageComboBoxItem.cs`
- [Item collection](https://github.com/zshameel/relink/blob/master/ImageComboBox/ImageComboBoxItemCollection.cs): control collection · Collection for image combo box items · `ImageComboBox/ImageComboBoxItemCollection.cs`

### Assets

Icons, resources, and selector metadata

- [Browser selector](https://github.com/zshameel/relink/blob/master/Config/BrowserSelector.xml): config metadata · XML metadata describing browser selection options · `Config/BrowserSelector.xml`
- [Resources](https://github.com/zshameel/relink/blob/master/Properties/Resources.resx): embedded assets · Shared icons and UI resource strings · `Properties/Resources.resx`

### Bootstrap

Application entry and project boundaries

- [App entry](https://github.com/zshameel/relink/blob/master/ReLinkMain.cs): startup · Program entry point that starts the WinForms application · `ReLinkMain.cs`

## Connections

- App entry → Main form: starts · Bootstraps the main WinForms shell
- Main form → Property service: binds · Uses observable state to keep the UI in sync
- Main form → Image combo: uses · Browser selection is driven through the custom combo box
- Main form → Browser settings: edits · Configures persisted browser-related preferences
- Main form → Toast: shows · Displays transient status messages
- Rule → Match type: depends on · Rules use match modes to compare URLs
- Rule → Wildcard: uses · Pattern matching supports rule evaluation
- Browser manager → Browser info: selects · Chooses a browser definition to launch
- Browser manager → Browser type: classifies · Uses browser type to branch behavior
- Browser manager → Rule: consults · Evaluates rules before launching a browser
- Browser manager → Browser settings: reads · Applies stored browser preferences
- Registrar → Win10 registrar: delegates · Uses version-specific registration flow when needed
- Registrar → Native helper: calls · Invokes native Windows integration helpers
- Registrar → OS version: branches on · Selects registration behavior by Windows version
- Image combo → Combo item: renders · Displays selectable browser items
- Image combo → Item collection: contains · Manages the item list for the dropdown
- Image combo → Resources: uses · Pulls in icons and embedded UI assets
- Property service → Properties: manages · Stores and updates observable properties
- Property service → Changed args: raises · Emits property change notifications
- Browser selector → Browser info: describes · Provides metadata for available browsers
- Main form → Browser manager: invokes · Triggers browser resolution and launch from the UI
- Toast → Resources: uses · Shares application icons and resource strings
- App entry → Registrar: initializes · Application startup prepares shell integration paths
