Every growing engineering team faces the same terrifying question: when do you stop hardcoding features and start building composable architecture? If you fail to time this decision correctly, you will either drown in duplicate code or trap yourself inside an abstraction that fights every new customer request. But if you follow the right composable architecture roadmap, you scale from one customer to twenty and beyond without ever needing a painful rewrite.

(Grateful to Mike Chen for his thoughts and ideas related to this writeup.)

The 3 Core Drivers of Composable Architecture Mistakes

Most engineering teams solve scaling problems in one of three ways, and each common approach carries a hidden cost. Understanding these drivers explains exactly why the roadmap below exists and why each step matters.

Abstracting Too Early

Teams often try to predict future needs and build flexible systems before they have real evidence those needs exist. This creates the wrong abstraction, which is far more expensive to unwind than simply duplicating code for a while.

Delaying the Deployment Decision

Some teams avoid choosing between isolated infrastructure and shared infrastructure until they are forced to. Waiting turns a simple decision into an agonizing, multi-week database migration or a tangled mess of patched-together code.

Scaling With Engineers Instead of Systems

Teams that never move past code-based customization stay dependent on engineers for every new customer. This blocks growth because onboarding speed is capped by how fast developers can write and deploy new code.

3-Phase Roadmap to Build Composable Architecture the Right Way

This roadmap follows the exact journey a growing product takes, starting with your very first customer and ending once you have twenty or more. Each phase unlocks the next, and skipping ahead too soon is exactly what causes the costly mistakes described above. The core principle running through every phase is simple: a wrong abstraction compounds in cost far faster than duplicate code does, so the roadmap deliberately waits to abstract anything until a feature has proven itself by repeating at least three times. This idea, often called the Rule of Three, exists because premature abstraction locks in assumptions about a feature before you actually know how it needs to vary.

Step 1: Build Standard and Explicit for Customer 1

What This Is

Write plain, unabstracted code built specifically for your first customer. No flexibility, no configuration, just a working product built fast.

Why It Matters

This step directly solves the "abstracting too early" driver. You cannot know what needs to be flexible until you have real customers proving it. Composable architecture built before that evidence exists is composable in name only.

How You Can Use It

Use The Explicit Build Sprint. This tool is a simple two-part approach: install an off-the-shelf UI framework like Shadcn or Tailwind UI on day one to skip writing custom CSS, and organize all code into strict, self-contained feature folders such as /features/billing. The single most important action is resisting any urge to add configuration options or plugin hooks before you have a second customer.

Examples (Toggle for more)

Less Productive: A team building a scheduling tool for their first customer spends two extra weeks building a flexible settings panel so future customers can customize every field, even though no second customer exists yet.
More Productive: The same team uses The Explicit Build Sprint.

Decision Logic Step 1 (Skip Custom Styling): The lead engineer asks, "Do we need custom design work right now?" The answer is no, so the team installs Tailwind UI on day one instead of building a design system from scratch.
Decision Logic Step 2 (Isolate by Feature): The team organizes the entire codebase into folders like /features/scheduling and /features/billing, keeping every piece of logic for one feature in one place rather than spreading it across shared utility files.
Decision and Output: The team ships to their first customer in three weeks instead of six. Because nothing was abstracted prematurely, when customer feedback later reveals which parts of the scheduling logic actually need to be flexible, the team can see it clearly instead of guessing.

Step 2: Choose Your Deployment Model & Extract The Core

What This Is

At customer number two, commit to either multi-instance or multi-tenant infrastructure, then pull shared code into a single core package before building anything customer-specific again.

Why It Matters

This step directly solves the "delaying the deployment decision" driver. Choosing now costs a small amount of upfront effort. Waiting until customer twenty means an agonizing database migration or a tangled, unsplittable codebase.

How You Can Use It

Use The Fork Point Decision Map. This tool is a two-option comparison: Option A, multi-instance, deploys the same codebase onto a new isolated server and database for total data separation, best for enterprise clients who demand it. Option B, multi-tenant, keeps all customers on shared infrastructure separated only by a tenant_id database column, best for standard SaaS scaling.

The single most important action is picking one option immediately and then extracting a shared core package so the original customer's application can be retrofitted to use it.

Examples (Toggle for more)

Less Productive: A team signs their second customer and, under deadline pressure, copies and pastes the entire codebase into a new folder, planning to "figure out the architecture properly later." Eighteen customers later, they are maintaining eighteen slightly different copies of the same application with no shared core.
More Productive: The same team uses The Fork Point Decision Map.

Decision Logic Step 1 (Choose the Deployment Model): The engineering lead asks, "Does this customer segment demand total data isolation, or can we scale on shared infrastructure?" Since the target market is small businesses without strict compliance needs, the team chooses Option B, multi-tenant.
Decision Logic Step 2 (Extract the Core): The team pulls authentication, the database client, and universal UI components into a single core package, then refactors the original customer's application to consume that core package instead of duplicating the logic.
Decision Logic Step 3 (Isolate the New Variation): Anything unique to the second customer is written as an isolated plugin that sits on top of the core package, leaving the core untouched and safe for every future customer.
Decision and Output: Onboarding customer three takes four days instead of three weeks, because the core package already exists and only a small plugin needs to be written. The team never faces a live-database migration, because the tenant_id column was built in from day one.

Step 3: Shift to Config-Driven Development at Customer 20+

What This Is

Replace code-based plugins and feature flags with a unified engine driven by a configuration file or database schema, so new customers can be onboarded without writing new code.

Why It Matters

This step directly solves the "scaling with engineers instead of systems" driver. By customer twenty, you finally have enough data to know exactly which fields and workflows are truly variable versus static, which makes configuration possible instead of guesswork.

How You Can Use It

Use The Configuration Engine. This tool is a single application engine driven by a JSON schema or configuration file that defines layouts, fields, and workflows without requiring a code deployment. The single most important action is waiting until you have a large enough sample size, roughly twenty customers, to know with confidence which parts of the product genuinely vary and which parts never change.

Examples (Toggle for more)

Less Productive: After twenty customers, a team still has forty different code-based plugins layered on top of their core package. Every new customer requires an engineer to write a new plugin, review it, and deploy it, which takes a week even for simple requests.
More Productive: The same team uses The Configuration Engine.

Decision Logic Step 1 (Identify True Variability): The team reviews all forty existing plugins and finds that almost all of them only ever changed three things: field labels, workflow order, and which notifications fire. Everything else stayed identical across every customer.
Decision Logic Step 2 (Build the Schema): The team builds a configuration file format that captures exactly those three variables, and rewrites the application engine to read from that configuration instead of from custom code.
Decision Logic Step 3 (Hand Off Onboarding): With the engine live, the customer success team is trained to onboard new customers by editing a configuration file directly, without needing an engineer at all.
Decision and Output: Customer twenty-one is onboarded in under an hour by a non-engineer, compared to the week it used to take. Engineering time is now reserved for building genuinely new capabilities instead of repetitive customer-specific plugins.

A Note on Composable Architecture and AI-Generated Code

A growing argument suggests skipping architectural planning entirely: feed your existing codebase to an AI model and prompt it to build something similar but different, generating a completely separate, disconnected repository each time. This is worth naming directly because it is a real temptation for teams trying to move fast.

The core issue is that large language models are fundamentally non-deterministic, meaning the same prompt can produce different results each time it runs. This forces you to hope the model correctly copies over every edge case, security rule, and business logic detail. If it hallucinates or skips a validation step, it introduces silent bugs that may not surface until production. When the stakes are high and stability matters, betting your scaling strategy on non-deterministic generation is a real business risk. Composable architecture still matters, and no amount of AI generation replaces the discipline of the roadmap above.

Actionable Tools for Composable Architecture

Checklist (Toggle for more)

Confirm you have not abstracted any feature until it has changed or repeated at least 2-3 times.

Script: "Has this exact pattern shown up in three separate places? If not, duplicate it and wait."

Lock in your deployment model decision at customer number two, not customer number twenty.

Script: "Do we need total data isolation, or can shared infrastructure with a tenant_id column work for this customer segment?"

Extract a core package before writing any customer-specific plugin.

Script: "Is this logic shared across customers? If yes, it belongs in the core package, not the plugin."

Wait until you have roughly twenty customers before building a configuration engine.

Script: "Do we have enough real examples to know what truly varies versus what stays the same?"

Reject any plan to replace architectural planning with AI-only code generation for production systems.

Script: "Can we verify every edge case this model copied over, or are we just hoping it worked?"

Toolkit (Toggle for more)

Composable Architecture Growth Map: The high-level diagnostic containing all three tools below, used to identify which phase of composable architecture your team is actually in right now.

The Explicit Build Sprint: A two-part approach using an off-the-shelf UI framework and strict feature folders to build fast for your very first customer without premature abstraction.
The Fork Point Decision Map: A two-option comparison between multi-instance and multi-tenant deployment, paired with a core-and-plugin extraction process used at customer number two.
The Configuration Engine: A JSON schema or configuration file system that replaces code-based plugins once you have enough customers, roughly twenty, to know what is truly variable.

FAQ: Composable Architecture

What is composable architecture?

Composable architecture is a system design approach where a shared core of code supports multiple customers or use cases, with unique variations built as isolated plugins or configurations rather than duplicated code. It allows a product to scale without rewriting the entire application for every new customer.

When should you start building composable architecture?

Start building it around your second customer, not your first and not your twentieth. Your first customer should get simple, hardcoded code so you can move fast and learn what actually varies. Waiting until you have too many customers makes the eventual transition to a shared core far more painful.

What is the difference between multi-tenant and multi-instance architecture?

Multi-tenant architecture means all customers share the same database and servers, separated by a tenant_id column, which keeps infrastructure costs low. Multi-instance architecture means each customer gets an isolated server and database, which costs more but guarantees that one customer's issue cannot affect another's data or uptime.

When should you NOT use composable architecture?

Skip building shared architecture too early, before you have at least two real customers proving which features actually need to vary. Building flexible systems based on guesses about future needs almost always produces the wrong abstraction, which is more expensive to undo than simply duplicating code for a while.

Can AI code generation replace composable architecture planning?

No, not for production systems where stability and security matter. Large language models are non-deterministic, meaning they can produce different results from the same prompt, which risks silently skipping critical business logic or security validations. Architectural planning remains necessary whenever the cost of a hidden bug is high.

How do you know when to move to config-driven development?

Move to a configuration-driven system once you have enough customers, typically around twenty, to clearly see which parts of your product are genuinely variable and which parts never change. Before that point, you do not have enough data to build a reliable configuration schema.

For more content like this, subscribe below 👇

Dan Wu, JD/PhD
Lead Innovation Advisor

I build and advise mission-driven ventures to scale like startups.

SVP of Product & Chief Strategy Officer.

As a go-to-market-focused product leader, I’ve led and launched products and teams at tech startups in highly-regulated domains, ranging from 6 to 8 figures in revenue.
Led core products and product marketing key to pre-seed to D raises across highly-regulated industries such as data/AI governance, real estate, & fintech; rebuilt buyer journeys to triple conversion rates; Won Toyota’s national startup competition.

Harvard JD/PhD focused on responsible innovation for basic needs.

Focus on cross-sector social capital formation, with a strong background in mixed-methods research.
Selected as a National Science Foundation fellow & published on responsible strategy and innovation in outlets like Oxford University Press, Fast Company, and TechCrunch.

First-generation college student prioritizing inclusion and belonging in his practice.

I was raised by a single mother without a high school degree.
I’m passionate about mentoring and coaching using methods that “works with” (versus “do to”), sensitive to one’s constraints and experiences.

Find me on Linkedin →

What is the Oh Crap Potty Training Method?

Composable Architecture: The 3-Phase Roadmap to Get It Right