Duplication Happened at Two Layers

The original split copied two layers of implementation that were still evolving. The Launcher layer was simply easier to see in Git history.

flowchart TB
    Template[HuixinLauncherTemplate]

    Template -. Copy origin .-> MainLauncher[XnneHangLabLauncher]
    Template -. Copy origin .-> ASRLauncher[ASRLauncher]
    Template -. Copy origin .-> TTSLauncher[TTSLauncher]

    MainLab[XnneHangLab] -->|launcher submodule| MainLauncher
    ASRLab[ASRLab] -->|launcher submodule| ASRLauncher
    TTSLab[TTSLab] -->|launcher submodule| TTSLauncher

    MainLauncher --> Shared[Independent copies of queue · process · logs · desktop shell]
    ASRLauncher --> Shared
    TTSLauncher --> Shared

flowchart TB
    XProduct[XnneHangLab product layer<br/>FastAPI · conversation · Profile · Live2D]
    AProduct[ASRLab product layer<br/>standalone recognition and future domain workflows]
    TProduct[TTSLab product layer<br/>WebUI · batch · presets · downloads]

    XASR[XnneHangLab ASR runtime<br/>Sherpa-ONNX · Qwen ASR]
    AASR[ASRLab ASR runtime<br/>FunASR · SenseVoice]
    XTTS[XnneHangLab TTS runtime<br/>Genie · GSV · Qwen]
    TTTS[TTSLab TTS runtime<br/>Genie · GSV · Qwen]

    ASRBase[Currently overlapping base ASR capabilities<br/>audio · VAD · transcription · timestamps · result contract]
    TTSBase[Currently overlapping base TTS capabilities<br/>resources · model lifecycle · reference audio · synthesis]

    XProduct --> XASR --> ASRBase
    AProduct --> AASR --> ASRBase
    XProduct --> XTTS --> TTSBase
    TProduct --> TTTS --> TTSBase

The Same Fix Becomes a Different Commit

ASRLauncher and TTSLauncher provide a direct example.

Each currently has 139 comparable source and configuration files, of which 135 are byte-for-byte identical. After the fork, six infrastructure commit pairs acquired different commit hashes while producing identical patches:

• a port conflict no longer terminates the development server immediately;
• file download progress remains visible under React 18 batching;
• an indeterminate animation appears when no percentage is available;
• tqdm logs update in place in the console;
• Rust splits stderr on \r and \n;
• child-process stderr is read as raw bytes.

These changes first appeared in TTSLauncher and were later replayed into ASRLauncher in the same order. Git sees two different commit sequences; their patch IDs show the same set of changes.

Launcher history provides the easiest symptom to quantify. The Lab layer does not necessarily produce matching commits: ASR migrated with a common contract and conversion logic before continuing to evolve, while TTS maintains parallel implementations of the same runtime responsibilities above common engines. The Git traces differ, but the architectural problem is the same: one shared semantic change must be reconsidered and revalidated in several places.

This is the point at which cross-repository cherry-picking becomes architecture.

A cherry-pick begins as a Git operation: apply one commit to another branch or repository. Once shared code has multiple maintained copies, however, it assumes an architectural responsibility: keeping those copies consistent.

flowchart TD
    Change[One change] --> Scope{Which layer owns it?}

    Scope -->|Launcher infrastructure| Launcher[XnneHangLabLauncher<br/>ASRLauncher · TTSLauncher]
    Scope -->|Base ASR semantics| ASR[XnneHangLab · ASRLab]
    Scope -->|Base TTS semantics| TTS[XnneHangLab · TTSLab]
    Scope -->|Product-specific workflow| Product[Modify only the owning product]

    Launcher --> VerifyL[Verify in three Launchers]
    ASR --> VerifyA[Verify in two ASR consumers]
    TTS --> VerifyT[Verify in two TTS consumers]
    Product --> VerifyP[Verify in the owning product]

    VerifyL --> Done[Propagation complete for this round]
    VerifyA --> Done
    VerifyT --> Done
    VerifyP --> Done

Typing git cherry-pick is not the expensive part. The expensive part is first determining which layer changed, then remembering which repositories currently contain that layer, and finally verifying the change in each product context.

The cost lies in the surrounding judgments:

1. Is this fix product logic or a shared mechanism?
2. Which other repositories have the same problem?
3. Have those implementations already developed different assumptions?
4. Can the patch be applied unchanged, or must it be adapted manually?
5. Which tests should run in each repository?
6. When a similar issue appears later, will I remember this propagation relationship?

Git can tell me whether a patch conflicts. It cannot tell me which other repository should receive that patch.

The Most Dangerous Case Is Not a Conflict, but No Conflict

Merge conflicts are the most visible problem in cross-repository synchronization, but they are not the most dangerous one.

A conflict interrupts the operation and clearly announces that two copies have diverged. The harder failures to discover are these:

First, a patch applies cleanly even though configuration semantics, error handling, or lifecycle assumptions have diverged between products. The code appears synchronized, but the behavior may no longer be equivalent.

Second, one repository is simply forgotten. It produces no conflict, does not fail CI, and leaves no error message. Only when the old bug reappears later does anyone discover that one copy remained in the past.

The central risk of cross-repository cherry-picking is therefore not that patches are difficult to merge, but that change propagation depends on maintainer memory.

flowchart TB
    Change[Shared semantics change] --> Memory{Maintainer identifies the owning layer}

    Memory --> Launcher[queue / process / logs]
    Memory --> ASR[ASR types / VAD / timestamps]
    Memory --> TTS[TTS lifecycle / resources / provider]

    Launcher --> L1[XnneHangLabLauncher]
    Launcher --> L2[ASRLauncher]
    Launcher --> L3[TTSLauncher]

    ASR --> A1[XnneHangLab]
    ASR --> A2[ASRLab]

    TTS --> T1[XnneHangLab]
    TTS --> T2[TTSLab]

    L1 --> Consistent[Copies temporarily consistent]
    L2 --> Consistent
    L3 --> Consistent
    A1 --> Consistent
    A2 --> Consistent
    T1 --> Consistent
    T2 --> Consistent

This dependency graph does not exist in code or a dependency manifest. It exists only in the maintainer’s head. The maintainer must remember not only that another copy exists, but exactly which repositories contain a particular semantic layer. A forgotten edge produces neither a conflict nor an automatic CI failure.

Every additional copy adds more than another file. It adds another propagation path, another context to understand, and another validation pass.

This cost also arrives unevenly. It hides during quiet periods and then erupts when shared mechanisms begin changing frequently. That makes copying easy to underestimate on the day it happens: the immediate gain is a complete runnable codebase, while the future synchronization obligation is recorded nowhere.

Six Repositories Do Not Create Six Maintainers

Independent repositories often create an illusion: once code has been separated, each repository can develop independently.

But an independent repository requires more than its own Git URL. It needs independent maintenance capacity:

• someone continuously handles its issues and dependency upgrades;
• it has its own tests and release schedule;
• it can decide independently how shared behavior should evolve;
• it can continue to be maintained even if the other repositories stop development.

If one person still maintains all six repositories, splitting them does not create more maintenance capacity. It divides the same attention across more contexts.

XnneHangLab and its Launcher continue to evolve actively, while ASRLab, TTSLab, and the two voice Launchers follow noticeably different commit, testing, CI, and release rhythms. In that situation, “identical code in independent repositories” does not mean the code gained independent maintainers. It means the same person must reconsider shared changes in more places.

This is also why satellite repositories tend to stagnate: repository independence isolates changes, but it also isolates the satellite from the fixes, tests, and continuous attention the main repository receives naturally.

Which Boundary Did I Split Incorrectly?

Looking back, the question is not whether splitting was inherently right or wrong. The problem was failing to separate five kinds of boundary first:

1. Source boundary: which code has exactly one maintenance source?
2. Repository boundary: which code must share one Git history?
3. Dependency and environment boundary: which capabilities need independent Python, CUDA, model, and system dependencies?
4. Artifact boundary: how many installers, images, or executables should be built?
5. Product boundary: how many distinct products do users see?

These boundaries may coincide, but they are not naturally identical.

flowchart TB
    subgraph Engines[Low-level engines]
        ASREngines[ASR engines]
        TTSEngines[TTS engines]
    end

    subgraph SharedSource[Shared source with one maintenance owner]
        ASRCore[ASRCore]
        TTSCore[TTSCore]
        LauncherCore[LauncherCore]
    end

    subgraph Products[Independent products and workflows]
        XLab[XnneHangLab]
        ALab[ASRLab]
        TLab[TTSLab]
        Launchers[Three thin Launchers]
    end

    subgraph Environments[Independent environments and artifacts]
        XArtifact[Companion environment and artifact]
        AArtifact[ASR environment and artifact]
        TArtifact[TTS environment and artifact]
    end

    ASRCore --> ASREngines
    TTSCore --> TTSEngines

    XLab --> ASRCore
    XLab --> TTSCore
    ALab --> ASRCore
    TLab --> TTSCore
    Launchers --> LauncherCore

    XLab --> XArtifact
    ALab --> AArtifact
    TLab --> TArtifact
    Launchers --> XArtifact
    Launchers --> AArtifact
    Launchers --> TArtifact

The sharing in this diagram happens at the source layer: the common ASR, TTS, and Launcher mechanisms each have one maintenance source. Products remain free to combine different capabilities, while environments retain independent Python, CUDA, model, and release artifacts.

What I actually wanted was independent dependency environments, specialist capabilities, and product artifacts. Instead, I also copied source code that would continue to change. Repository splitting solved environment isolation while creating a source synchronization problem.

Code Duplication Is Not the Original Sin; Duplicated Evolution Is

Not every copy creates this debt.

If a template is copied and the resulting projects are then allowed to diverge independently, with no expectation of future synchronization, it is simply a shared historical starting point. Their subsequent divergence is fine.

If a piece of code is extremely stable and almost never changes, the long-term cost of copying it may also be lower than the complexity of introducing a shared dependency.

The risky code has a different profile:

• it belongs to infrastructure or a shared mechanism;
• it is still being fixed and extended frequently;
• several products expect to keep receiving those updates;
• it has no explicit unique maintenance source;
• propagation depends on maintainer memory and cross-repository cherry-picks.

At that point, what was copied was not merely a source snapshot, but its entire future change history.

The debt can be understood roughly as:

Maintenance debt ≈ number of copies × shared-code change frequency × propagation judgment cost × per-repository validation cost

This is not a formula for calculating engineering hours. It explains why copying one more repository feels almost free today while its long-term cost can grow rapidly.

How to Pay Down the Debt in Engineering Terms

For a general reader, the broad conclusion is already enough: do not mistake a repository boundary for a module boundary.

For these three Labs and three Launchers, however, one question remains: how can the overlapping implementation gain one maintenance source while product capabilities remain free to diverge?

flowchart TB
    subgraph Products[Products and domain workflows]
        XLab[XnneHangLab<br/>companion · conversation · Profile · Live2D]
        ALab[ASRLab<br/>standalone recognition · extensible workflows<br/>future: speaker diarization]
        TLab[TTSLab<br/>WebUI · batch · presets · distribution]
    end

    subgraph DomainCores[Domain inference Cores]
        ASRCore[ASRCore<br/>transcription · VAD · timestamps · result contract]
        TTSCore[TTSCore<br/>provider · model lifecycle · synthesis contract]
    end

    subgraph Engines[Low-level engines]
        ASREngines[FunASR · Sherpa-ONNX · Qwen ASR]
        TTSEngines[Genie-TTS · GSV-Lite · Faster-Qwen-TTS]
    end

    XLab --> ASRCore
    XLab --> TTSCore
    ALab --> ASRCore
    TLab --> TTSCore

    ASRCore --> ASREngines
    TTSCore --> TTSEngines

flowchart TB
    XASR[XnneHangLab ASR integration] --> ASRCore[ASRCore]
    ABase[ASRLab base recognition] --> ASRCore
    Diarization[Speaker diarization] --> ABase
    Subtitle[Future: subtitle and dataset pipelines] --> ABase

    XTTS[XnneHangLab TTS integration] --> TTSCore[TTSCore]
    TBase[TTSLab base synthesis] --> TTSCore
    Batch[Batch processing and presets] --> TBase
    Distribution[Model downloads and standalone distribution] --> TBase

flowchart TB
    XLab[XnneHangLab] --> ASRCore[ASRCore]
    XLab --> TTSCore[TTSCore]
    ALab[ASRLab] --> ASRCore
    TLab[TTSLab] --> TTSCore

    XLab -->|launcher submodule| XL[XnneHangLabLauncher]
    ALab -->|launcher submodule| AL[ASRLauncher]
    TLab -->|launcher submodule| TL[TTSLauncher]

    XL --> LauncherCore[HuixinLauncherCore]
    AL --> LauncherCore
    TL --> LauncherCore

    Template[HuixinLauncherTemplate] -. Preserve history and transform .-> LauncherCore

flowchart TB
    Freeze[Stop adding cross-repository copies<br/>record current ASR/TTS behavior contracts]
    TTS[Extract TTSCore<br/>combine mature behavior from both sides]
    ASR[Extract ASRCore<br/>unify contracts and register three adapter families]
    Satellites[Connect ASRLab / TTSLab first<br/>as independent reference consumers]
    Main[Connect XnneHangLab<br/>remove duplicate runtime after parity tests]
    Launcher[Transform Template into LauncherCore<br/>migrate the three Launchers in sequence]
    Version[Only upgrade Core versions afterward<br/>verify each consumer independently]

    Freeze --> TTS --> ASR --> Satellites --> Main --> Launcher --> Version

Questions I Will Ask Before Splitting Repositories Again

Before making a similar split in the future, I will answer these questions:

1. Am I trying to isolate source code, dependencies and runtime, release artifacts, or user-facing products?
2. Will the copied code continue to evolve?
3. After fixing one copy, are the other repositories still expected to receive the fix?
4. What is the unique maintenance source for this shared code?
5. Is change propagation handled by dependencies and versions, or by maintainer memory?
6. Does every repository really have independent maintainers, tests, and release schedules?
7. If a satellite repository stagnates for a year, can the main product still change the shared mechanism safely?
8. If the answer is still “modify this repository, then cherry-pick the others,” what did the repository boundary actually isolate?

One rule is more useful than all the others:

If shared code is still expected to evolve in sync, give it one maintenance source before deciding how different products will consume it.

Closing

Repository splitting solves real problems: heavy dependencies, different runtime environments, different release schedules, different users, and different product forms.

But a Git repository is only a storage and collaboration boundary. It does not automatically create module boundaries or erase evolutionary relationships between pieces of code.

The lesson from three Labs and three Launchers is not that there are too many repositories. It is that I once mistook “the code lives in different repositories” for “the code is independent.” As long as one shared fix must propagate across repositories, those repositories remain coupled. The coupling is no longer expressed by imports or dependency manifests, but by cherry-picks, manual judgment, and maintainer memory.

That coupling is less visible and therefore easier to underestimate.

For a general reader, the conclusion can end here. For this repository family, the engineering outcome is more concrete:

• move currently overlapping base implementations into ASRCore, TTSCore, or LauncherCore so each has one maintenance source;
• keep future product divergence above the Core while continuing to build independent artifacts;
• give low-level engines, domain inference, product workflows, and desktop infrastructure separate boundaries;
• replace cherry-pick propagation with explicit dependency-version upgrades;
• use templates only to generate projects intended to diverge independently, never as a long-term update channel.

Splitting repositories is not decoupling. Copying shared code that is still evolving merely converts code coupling into synchronization coupling—and eventually into maintenance debt.