The real problem with duplication

Having two implementations of one system didn’t look like a problem to me at first, I built it once and it worked, then I re-implemented the same system again in another language, keeping feature parity and that also still worked.

I'm building ExplainThisRepo, a CLI tool for understanding unfamiliar codebases that shows you where to start, what matters and what to ignore using real signals; entrypoints, configs, dependencies, manifests, not blind AI guessing

Before now every time I ship a feature I’m not building it once, I’m actually building it twice, same with bugs, I’m not fixing them once, I’m fixing them twice

Initially it seemed manageable, but what I had actually created was two sources of truth.

And now I also have to make sure both implementations behave the same way in different languages: Python and TypeScript

They were not wrappers of each other, they were just two independent systems with the same features, behavior, outputs and edge cases, implemented differently in each language, and I had to keep aligning them and maintaining ecosystem feature parity.

That slowed everything down and was very painful to maintain alone

At some point, I stopped moving fast not because the system was complex, but because I was maintaining two of everything.

So I removed the duplicate TypeScript implementation, deleted ~1300 lines and made Python the only core implementation and source of truth, Node now only bundles into npm distribution and launches the Python binary, it no longer runs any logic, all the logic lives in Python.

All the CLI behavior, repo analysis, providers, output, everything, runs inside the prebuilt Python binary. It runs without requiring Python installed on the user's machine. No duplication, one system

Link to PR: https://github.com/calchiwo/ExplainThisRepo/pull/208

Why Python became the core implementation

The decision was not about “which language is better”, it was:

Which implementation should remain as the single source of truth?

One system should have one source of truth, everything else is distribution.

I chose Python because it’s the correct long-term place for the system to live. It was already the implementation I was building on most actively, new features were landing there first and that’s where the system was already evolving.

In short Python was where the core logic was stable and iteration was fastest

Keeping TypeScript as the core would mean either shifting development entirely to it or continuing to duplicate work, both increase long-term cost.

So instead of moving the system, I kept it where it was already being developed, removed the TypeScript implementation, and made Python the only core implementation, Node now just acts as a launcher for the Python binary and distribution.

Why maintaining both breaks down over time

At that point, it was tempting to say:

“I’ll just keep both implementations and manage them”

and yeah that works early but it doesn’t scale.

Because the real cost isn’t just duplication, it’s coordination, you now have to keep both implementations aligned, every change now means doing the same work twice, making sure behavior matches, remembering what changed where, and that turns simple changes into tracking problems, so you hesitate to ship, small differences start creeping in, edge cases multiply and over time the system becomes harder to trust, harder to maintain and slower to evolve.

This gets worse when you’re maintaining it alone, there’s no distribution of effort, you’re the one building, reviewing and maintaining consistency, and at some point it slows everything down not because the system is complex, but because you’re maintaining two of everything.

The hidden trap is this: duplication creates the illusion that things are fine, but in reality it removes clarity, you no longer have one system (or single source of truth) you can reason about, you now have two systems that must stay consistent, and that is a fundamentally harder problem.

What this actually is

This isn’t just a refactor, it’s a correction, I moved from a multi-runtime tool to a single-engine product with a distribution wrapper, the mistake was letting the same system exist in multiple places, so I changed how it’s distributed, Node no longer re-implements anything, it just detects your OS, picks the right binary and executes it as a separate process.

When to use this approach

This pattern works when:

• you need to distribute across multiple ecosystems without rewriting the system
• the interface is clear and bounded (clear inputs, a defined process and predictable outputs)
• cross-runtime execution is acceptable

Common cases:

• CLI tools
• automation tools
• backend services with well-defined boundaries
• internal tools shared across environments

When not to use it

This pattern does not fit when:

• you’re building libraries that must run inside a specific runtime
• tight, in-process integration is required
• performance is sensitive to process startup or cross-runtime latency
• the system relies heavily on features tied to a specific runtime

The test

Before you build the same system twice, ask:
If I change this tomorrow, do I have to update it in more than one place?
If the answer is yes, you don’t have one system, you have duplication.
And if you keep going, you’re choosing coordination over progress.
You don’t fix duplication by maintaining it better, you fix it by removing the second place it exists

Tradeoffs

This change simplifies the system, but it isn’t free, bundling Python into the npm package increases the binary size so install size goes up compared to a pure Node tool, startup also has a cost because the Node launcher starts a separate Python process which adds extra startup time before execution, cross-platform support becomes more complex since you now need to build and maintain binaries for different operating systems and architectures, and debugging is less direct because issues can sit across the boundary between Node and Python, so you end up tracing problems across two environments.

These are real costs, but they are contained costs, not duplicated logic, and I chose to pay them because they scale better long-term than maintaining two implementations of the same system.

The conclusion

Maintaining both is not something you can sustain, the cost keeps increasing over time until it forces a decision, you either accept the growing cost or enforce a single source of truth, I chose the second.