From Fork to Framework, Part 1: Standing on Shoulders

A fork-based strategy can feel like a shortcut to shipping production software fast — right up until the shortcut turns into a detour. This is an honest, timeline-by-timeline account of what happened when we built the first generation of AOCyber on top of two open-source forks, and why we eventually abandoned both. If you are weighing a fork-based strategy for your own product right now, the architecture, the week-by-week history, and the hard lessons below should save you real engineering time — and possibly save you from repeating our 759-file merge.

What Is a Fork-Based Strategy? Definition, Benefits, and Hidden Costs

In software development, a software fork happens when a team copies an existing codebase and develops it independently from the original project. A fork-based strategy, then, is the deliberate business decision to build your product on top of one or more of these forks instead of starting from a blank repository.

On paper, the benefits are obvious. You inherit years of upstream commits, a working CI pipeline, and a community that has already filed the bugs you would have discovered the hard way. For example, our first fork arrived with a functioning multi-container deployment on day one — something that typically takes a greenfield team weeks to assemble. In addition, you inherit documentation, test coverage, and a user base that already trusts the underlying product.

However, every one of those benefits comes attached to a cost that rarely shows up in the first sprint planning meeting. Specifically, a fork-based strategy means you no longer fully control your own architecture, your own release cadence, or your own data model. As a result, every customization you layer on top becomes a liability the moment upstream changes direction. This is the tension at the center of our story.

The Two Forks We Chose for Our Open-Source Fork Strategy

On October 2, 2025, we created two repositories that would anchor our fork-based strategy for the next ten weeks:

• AOCodex (since renamed to AODex to avoid confusion with OpenAI's Codex product), forked from LibreChat by Danny Avila. LibreChat is a TypeScript/React/Node.js chat application with over 3,200 upstream commits at the time of our fork. It gave us a polished multi-model chat UI, conversation management, a plugin architecture, and a MongoDB persistence layer — essentially, a production-ready ChatGPT alternative we could rebrand and extend.
• AOSentry, forked from LiteLLM by BerriAI. LiteLLM is a Python proxy that presents a unified OpenAI-compatible API across dozens of model providers — a foundational piece of what we now call a multi-model AI strategy. With over 26,000 upstream commits, it is one of the most actively developed projects in the LLM infrastructure space. It gave us provider abstraction, token tracking, rate limiting, and a Next.js admin dashboard.

Together, these two forks formed the backbone of our v1 architecture. In other words, our entire fork-based strategy rested on two projects we did not control, built by maintainers whose priorities were — quite reasonably — not ours.

Inside the V1 Architecture Built on Forked Code

The architecture split responsibilities cleanly in theory: AODex owned the user experience, conversation state, and authentication, while AOSentry owned model routing, cost tracking, and provider failover. In practice, the boundary was messier than it looked on a whiteboard. Both projects carried their own admin UIs, their own authentication systems, and their own opinions about how to talk to a database.

AODex (React + Node.js + MongoDB)
  Frontend (TypeScript, Recoil/Jotai) --> API (Express)
  API --> MongoDB

AOSentry (Python FastAPI + Prisma + PostgreSQL)
  Proxy --> Prisma ORM --> PostgreSQL
  Admin UI (Next.js) --> Proxy
  Celery Workers --> Proxy

Shared Infrastructure
  AODex API --> AOSentry Proxy (AI requests)
  AOSentry Proxy --> Redis (shared cache)
  AOSentry Proxy --> OpenAI, Anthropic, Azure, Bedrock

Put simply: two independently-governed codebases, two databases, two admin panels, and one shared Redis layer trying to hold it all together. That is the architectural reality underneath almost every fork-based strategy that stitches two mature open-source projects together.

The 10-Week Timeline: How Our Forking Strategy Unfolded, Week by Week

What follows is the condensed story of roughly ten weeks on AODex and ten weeks on AOSentry. The branch names in our git history tell it more honestly than any retrospective could.

Week 1-2 (October 2-15, 2025): The Honeymoon Phase

Everything moved fast. We rebranded both projects, swapped color schemes, configured CI, and deployed to staging. AODex inherited LibreChat's Docker Compose setup, so we had a working multi-container environment on day one. Similarly, AOSentry's proxy layer worked immediately with our existing OpenAI and Anthropic API keys.

The first custom features landed quickly: Stripe billing integration on AODex, personally identifiable information (PII) detection using Microsoft Presidio on AOSentry, and a shared guardrails pipeline that could intercept prompts before they reached a model provider — the same category of defense we later deepened in our work on jailbreak detection for enterprise AI.

Week 3-5 (October 16 - November 5, 2025): Divergence Begins

We were committing heavily — AODex would accumulate 522 custom commits by December 12. Features included admin dashboards, Docker Swarm deployment manifests, and multi-architecture container builds for ARM and x86. Each feature, however, pulled us further from upstream.

The Recoil-to-Jotai migration was our first taste of upstream turbulence. LibreChat switched its state management library mid-stream, and because we had modified dozens of components that imported Recoil atoms, the migration touched files across our entire fork. It was a three-day detour that delivered zero user-facing value — a cost that almost never appears in a fork-based strategy's original business case.

Week 6-7 (November 6-19, 2025): The 759-File Merge

The branch feature/AOC-61-merge-latest-librechat-code tells the story of our attempt to pull in LibreChat v0.8.1-rc1. The merge produced 759 file conflicts. Not 759 lines — 759 files. If you have never run a git merge at that scale, it is worth understanding that the official Git documentation treats conflict resolution as a manual, line-by-line process with no shortcut for codebases that have diverged this far.

Some of these conflicts were trivial: both sides had touched package.json or configuration files. Many were not. Our Stripe billing hooks had been wired into LibreChat's user model, which upstream had restructured. Our guardrails middleware sat in a request pipeline that upstream had refactored. In particular, our admin dashboard components imported utilities that upstream had moved to different modules entirely.

We created a branch named backup-pre-librechat-merge-20251112 before attempting the merge — a name that radiates confidence. The merge took five full engineering days to resolve, test, and stabilize. During that time, no product features shipped at all.

Week 8-10 (November 20 - December 12, 2025): The LangChain Saga

On AOSentry's side, the LangChain v1 upgrade became the equivalent of the 759-file merge. LangChain's migration from v0 to v1 changed import paths, renamed core abstractions, and deprecated patterns we had built on top of. Because AOSentry inherited LiteLLM's LangChain integration, and we had extended it with custom chain logic for our guardrails pipeline, the upgrade cascaded through a significant portion of our codebase.

Meanwhile, the refactor/remove-litellm-branding branch represented our effort to white-label AOSentry. Rebranding a project with 26,000 commits is not a find-and-replace operation. The name appeared in log messages, error strings, API response headers, database migration comments, documentation, Docker image tags, environment variable prefixes, and even Prometheus metric names. Every occurrence had to be evaluated: some were internal, some were user-facing, and some were contractual — LiteLLM's enterprise license, which we needed to remove entirely and replace with our own licensing logic.

December 12, 2025: The Decision Point

By mid-December, we had 522 custom commits on AODex and 188 on AOSentry. We had built real product value: Stripe billing, PII detection, content guardrails, admin dashboards, Docker Swarm orchestration, and multi-arch builds. That said, we had also spent a disproportionate amount of engineering time on merge conflicts, upstream migrations, and rebranding work that did not move the product forward.

The fork-based approach carried another cost that is harder to quantify: an architectural ceiling. Both upstream projects made reasonable choices for their own use cases that were wrong for ours. LibreChat used MongoDB because document storage is natural for chat conversations — but we needed relational integrity for billing, teams, and access control. LiteLLM used Prisma with PostgreSQL, which was closer to what we wanted, but its schema was optimized for a proxy's concerns rather than a product's concerns. This is a point we explore further in why your data isn't a moat — the underlying architecture you inherit shapes what your product can defensibly become. Consequently, we could not change the database layer of either fork without essentially rewriting them. And if we were going to rewrite them, the fork was no longer saving us any time.

What We Built That Mattered: Capabilities That Survived the Fork

It is important to acknowledge what the fork period produced beyond frustration. Several capabilities we prototyped during these ten weeks survived into later iterations of the product, which is a useful reminder that a fork-based strategy is not purely a cautionary tale — it is also a legitimate prototyping tool when used with a clear exit plan.

In short, the fork period was not wasted. It was a rapid, high-fidelity prototyping phase that taught us what our product needed to be. The mistake would have been staying in that phase longer than necessary — which brings us to the decision framework every team should run before committing to a fork-based strategy.

Fork-Based Strategy vs. Clean-Room Rewrite: A Decision Framework

Most articles on forking stop at "forks save time at first, then cost time later." That is true, but it is not actionable. Below is the framework we wish we had used before October 2, 2025, broken into the dimensions that actually predict whether a fork-based strategy will pay off.

• Data model fit: If the fork's database schema already matches your core entities (users, billing, permissions), a fork-based strategy is low-risk. If you need to bolt on relational concerns to a document-store fork, or vice versa, expect an eventual rewrite.
• Upstream velocity: A highly active upstream project delivers more free features, but also more breaking changes. Calculate your merge frequency tolerance before you fork, not after your first 759-file conflict.
• Customization depth: Surface-level theming and configuration rarely cause problems. Deep modifications to authentication, billing, or request pipelines — the exact areas we touched — are where a fork-based strategy accumulates its heaviest tax.
• Rebranding scope: If your business model requires removing the upstream project's identity entirely (as ours did with LiteLLM's enterprise license), budget weeks, not days, for that work alone.
• Exit criteria: Decide in advance what signal will tell you the fork has become a liability. For us, it was the 759-file merge combined with the realization that we could not change either database layer without a full rewrite.

How to Decide If a Fork-Based Approach Fits Your Product

Use this sequence before you commit engineering time to any fork. It took us ten weeks to learn it; it should take you about an afternoon to apply it.

The Lessons: Five Rules for Evaluating a Fork-First Approach

1. Forks are prototypes, not foundations

A fork gives you a running start on features, but it also gives you a running start on technical debt. Every upstream merge is a tax. Every upstream architectural decision you disagree with becomes a constraint. In particular, the more you customize, the higher the tax and the tighter the constraints become.

2. Upstream velocity is a double-edged sword

We chose LibreChat and LiteLLM partly because they were active projects with strong communities. That activity meant free bug fixes and new features — but it also meant the codebase was a moving target. A dormant upstream is easier to fork; an active upstream is more valuable to fork but harder to maintain.

3. Rebranding is architectural work, not cosmetic work

Removing another project's identity from a large codebase touches error handling, logging, metrics, documentation, environment variables, API contracts, and sometimes licensing. Therefore, budget for it accordingly, or accept that your product will carry another project's name in places your customers might see.

4. The merge conflict is the symptom, not the disease

The 759-file merge was painful, but the real problem was that we had made 522 custom commits in a codebase we did not control. Every custom commit increased the surface area for future conflicts. There is no tooling that solves this; it is a fundamental tension in any fork-based strategy.

5. Measure total cost of ownership, not just time-to-launch

A fork-based strategy looks cheap in week one because you are only measuring setup time. By contrast, the true cost includes every future merge, every upstream migration, and every hour spent explaining to a new engineer why the codebase does things a certain way "because that's how upstream did it." Track that number from day one, not from the day it becomes painful.

When Forking Makes Sense (and When It Doesn't)

To be clear, we are not arguing that forking is always a mistake. A fork-based strategy makes sense when you need a working proof of concept fast, when your customizations will stay shallow, or when you plan to use the fork as a throwaway prototype rather than a permanent foundation. Above all, it works best when you treat the fork as a library dependency rather than a codebase you will rewrite internally — exactly how we now consume LiteLLM's provider abstraction.

In contrast, a fork-based strategy makes less sense when your product's core value depends on a data model the fork was never designed to support, when you need deep changes to authentication or billing, or when upstream churn is high enough that you will spend more time merging than building. If two or more of these conditions apply to your project, a clean-room build — however slower it feels at first — will almost always be cheaper within six months.

Credit Where It's Due

Danny Avila's LibreChat and BerriAI's LiteLLM are excellent projects. LibreChat gave us a mature, well-tested chat interface that would have taken months to build from scratch. LiteLLM's provider abstraction layer is genuinely best-in-class — we still use it today, as a dependency rather than a fork. Both projects have active communities, responsive maintainers, and clear roadmaps.

Our decision to move away from the forks was not a commentary on their quality. It was a recognition that our product requirements had diverged far enough from their goals that maintaining alignment was costing more than building independently.

What Came Next: From Fork to Framework

The fork experiment ended in mid-December 2025. What replaced it was a clean-room rewrite using FastAPI and SvelteKit — a story with its own victories and its own hard lessons, continued in Part 2. That rewrite eventually matured into the workflow we use today, which we document in detail in our Claude Code DevFlow write-up, and which now runs on our own DevFlow framework. In short, abandoning the fork-based strategy was not the end of the story — it was the beginning of the one we actually wanted to tell.

Frequently Asked Questions About Fork-Based Strategy

What is a fork-based strategy in software development?

A fork-based strategy is the practice of copying an existing open-source codebase and building your product directly on top of it, rather than writing the application from scratch. It inherits the original project's features, bug fixes, and community, but also its architectural constraints and update cadence.

When does a fork-based strategy make sense for a startup?

It makes the most sense for rapid prototyping, validating a market before committing to a full build, or when your planned customizations stay shallow enough that they won't fight the fork's existing data model. In those cases, a fork-based strategy can shave months off your time to first demo.

What are the biggest risks of a fork-based strategy?

The biggest risks are escalating merge conflicts as both codebases diverge, an architectural ceiling imposed by a database or framework choice you did not make, and the hidden engineering cost of fully rebranding a project that was never designed to be white-labeled.

How do you know when to abandon a fork-based strategy?

Watch for three signals: merge conflicts that span hundreds of files instead of dozens, a database or framework limitation you cannot work around without a rewrite, and a realization that rebranding work is consuming more time than product development. When two or more of these appear together, it is usually time to plan a clean-room rewrite.

Is forking an open-source project the same as a fork-based strategy?

Not quite. Forking is the technical act of copying a repository. A fork-based strategy is the broader business decision to build and ship a commercial product on top of that fork long-term, which carries ongoing obligations around upstream merges, licensing, and rebranding that a simple technical fork does not.

What is the alternative to a fork-based strategy?

The main alternative is a clean-room rewrite: building your own codebase from scratch while using mature open-source libraries, like a provider-abstraction package, as dependencies rather than forked code. This trades a slower initial start for full control over your data model, release cadence, and licensing — control we did not have while running AODex and AOSentry as forks.

Final Thoughts: Weighing a Fork-First Strategy for Your Next Build

A fork-based strategy is neither a trap nor a silver bullet — it is a tool with a narrow window of usefulness. Used as a rapid prototyping phase with a clear exit date, it can teach you exactly what your product needs to become, just as it did for us with Stripe billing, PII detection, and our guardrails pipeline. Used as a permanent foundation, however, it will eventually collide with an architectural ceiling you cannot merge your way past. Our 759-file merge, our LangChain migration, and our months of rebranding work were the price of learning that lesson the hard way. If you take one thing from this timeline, let it be this: evaluate your fork-based strategy on a fixed schedule, measure total cost of ownership rather than time-to-launch, and be willing to walk away the moment the fork stops saving you time.