> For the complete documentation index, see [llms.txt](https://wiki.crosswatch.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.crosswatch.app/crosswatch/main-dashboard/tools/sync-topology-advisor.md). # Sync topology advisor Visualize enabled sync routes and identify potential conflicts, loops, and redundant paths. Visualize how enabled sync pairs connect. Identify routes that need closer review. The Sync topology advisor analyzes your current CrossWatch configuration. It turns that configuration into a visual map. It highlights multiple writers, return routes, redundant paths, and complex topologies. {% hint style="info" %} The advisor is read-only. It analyzes enabled pairs locally. It never changes provider data or pair settings. {% endhint %}
### What it analyzes The advisor builds its topology from: * Enabled sync pairs * Enabled features in those pairs * Configured source and target provider instances * One-way and two-way pair direction * Provider feature support * Pair-specific feature rules * The selected profile, when active Each synchronization feature is analyzed separately. Results combine into the complete topology view. Media filters, library scopes, and CrossWatch safeguards can reduce actual overlap. The advisor shows configuration paths, not live provider values. ### Topology health The main dashboard shows a **Topology health** summary. It includes: * Active pair count * Detected conflicts and loops * Suggestions | Status | Meaning | | ---------------------- | ---------------------------------------------------------------------------------------------- | | **No active pairs** | No enabled sync pairs are available to analyze. | | **Healthy** | No conflicting writers or return routes were detected. Observations may still be available. | | **Review recommended** | Some routes need review. Enabled features may also be unavailable. | | **Attention required** | A higher-risk multiple-writer situation was detected. Ratings and Progress routes can compete. | Select **View topology** to open the complete graph. When findings are available, select **Review findings**. The graph opens on the first finding. ### Reading the topology The graph shows each configured provider instance as a separate node. Connections show enabled sync routes. * **→** means one-way * **↔** means two-way * Numbered badges identify each configured sync pair Instances of the same provider appear as separate nodes. The selected profile also appears when the dashboard is scoped to one. #### Filter by feature Use the buttons above the graph to show all enabled features or one feature. The advisor creates these buttons from active topology features. Filter by feature when the complete graph becomes busy. A Watchlist route may be simple. Ratings or Progress may follow different paths. #### Route details Expand **Route details** below the graph to list configured connections. Each route shows: * Pair number * Source and target provider * One-way or two-way direction * Features carried by that route ### Findings The right side of the advisor contains **Topology health** findings. Select one to highlight affected providers and routes. #### Updates from multiple providers CrossWatch detected more than one provider writing the same feature to one destination. ``` Plex → Trakt SIMKL → Trakt ``` Both Plex and SIMKL can send the same feature to Trakt. This is a potential conflict. It does not prove data was overwritten. A problem occurs only when providers disagree about the same item. Ratings and Progress receive higher severity because their values can compete directly. Recommended action: * Choose an authoritative provider for the feature * Remove an unnecessary writer * Use one-way pairs where only one provider supplies updates #### Shared two-way updates A destination is connected to several providers through expected two-way pairs. ``` Plex ↔ Trakt SIMKL ↔ Trakt ``` This is informational, not an automatic conflict. Each linked provider can update the value. Different Ratings or Progress values can still compete. Keep this topology when changes need to flow both directions. Otherwise, use one-way pairs to clarify the source. #### Return route through additional pairs A feature can return to its starting provider through separately configured pairs. ``` Plex → Trakt Trakt → SIMKL SIMKL → Plex ``` The advisor highlights an example return path. This does not mean CrossWatch enters an infinite loop. CrossWatch has sync safeguards. The extra route can cause unnecessary provider activity. It also makes behavior harder to reason about. Recommended action: * Remove routes without a specific purpose * Choose a clear source of truth * Avoid circular paths only to connect every provider #### Potential redundant route The same feature can reach a destination through multiple paths. ``` Plex → Trakt Plex → SIMKL → Trakt ``` Both paths carry data from Plex to Trakt. The advisor can also detect multiple pairs carrying one feature over the same route. This can work. The extra path can create unnecessary provider activity. Recommended action: * Keep the shortest or clearest route * Remove duplicate pairs serving the same purpose * Keep alternate paths only when intentional #### Consider simplifying your routes A larger topology can be valid without conflicts, loops, or redundant paths. When a feature spans many provider instances, the advisor may suggest a central source. This can make the configuration easier to maintain. This is only an observation. Keep every route that has a clear purpose. #### Unsupported or unavailable routes The graph omits enabled pair features CrossWatch cannot use for the configured provider combination. The advisor shows a review notice when this occurs. Check the affected pair: * Both providers support the feature * The provider combination allows the feature * The pair mode supports the feature * Intended provider instances are selected The advisor only draws routes available for the configured pair. ### Graph controls The topology graph supports zooming and panning. Use: * **+** to zoom in, or **−** to zoom out * The slider to set the zoom level * **Fit** to reset and fit the graph * Drag or arrow keys to pan Zoom ranges from 50% to 250%. On narrow screens, the graph uses a compact vertical layout. ### Highlighting findings Selecting a finding: 1. Switches the graph to the related feature. 2. Highlights affected routes and providers. 3. Shows additional advice. Other routes are muted. Select the finding again, or select **Clear highlight**, to restore the normal graph. ### What the advisor does not tell you The advisor analyzes configuration, not provider contents. It does not: * Compare Ratings, Progress, or Watchlist values * Prove a conflict already happened * Predict exact changes in the next sync * Replace Interactive Sync review * Change pair settings or provider data A finding means the configured routes make a situation possible. Use [Interactive Sync](/crosswatch/main-dashboard/interactive-sync.md) to review the exact changes planned for a sync. ### Recommended workflow Use the advisor after creating or changing several sync pairs. 1. Check **Topology health** on the main dashboard. 2. Open **View topology**. 3. Filter the graph by feature. 4. Review multiple-writer findings first. 5. Review additional return routes. 6. Remove duplicate or unnecessary paths. 7. Confirm each feature has a clear source of truth. 8. Run affected pairs and review changes with Interactive Sync. {% hint style="warning" %} A connected topology is not automatically a good topology. More routes create more chances for data to return, overlap, or compete. Keep only the routes you need. {% endhint %} ### Common examples #### Simple one-way setup ``` Plex → Trakt ``` This is the easiest topology to reason about. Plex supplies enabled features to Trakt. #### Central provider ``` Plex → Trakt Jellyfin → Trakt ``` This can work when Trakt intentionally receives updates from both media servers. The advisor can flag overlapping features as multiple writers. #### Chained route ``` Plex → Trakt → SIMKL ``` Data can travel through the chain without returning. If Plex also writes directly to SIMKL, the advisor can identify an alternate path. #### Circular route ``` Plex → Trakt Trakt → SIMKL SIMKL → Plex ``` The feature can return to Plex through separate pairs. CrossWatch can process this configuration. The advisor recommends reviewing whether the full circle is needed. ### Troubleshooting #### No active routes yet The topology contains no supported enabled feature routes. Check that: * At least one sync pair is enabled * At least one pair feature is enabled * Configured providers support that feature #### Some enabled features are missing The provider combination or pair mode may not support the feature. Open pair settings and review the enabled feature. #### The graph shows routes from the wrong profile The advisor follows the profile selected on the main dashboard. Switch profiles, then reopen the topology. #### A finding does not match sync behavior The advisor analyzes possible configuration overlap. Actual behavior can be reduced by library scopes, media filters, provider capabilities, and CrossWatch safeguards. Use Interactive Sync to review planned changes for a run. ### Related topics * [Configure Pairs](/crosswatch/settings/configure-pairs.md) * [Interactive Sync](/crosswatch/main-dashboard/interactive-sync.md) * [Editor](/crosswatch/main-dashboard/navigation/editor.md) * [Analyzer](/crosswatch/main-dashboard/tools/analyzer.md) * [Best practices](/getting-started/best-practices.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://wiki.crosswatch.app/crosswatch/main-dashboard/tools/sync-topology-advisor.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.