This is an article about a small structural practice that changed how my team makes architectural decisions, how we talk to enterprise buyers during security reviews, and how we avoid the slow drift from "building the right product" to "marketing a product we haven't built yet."

The practice is simple: every major architectural component in our PRD has two sections. One is called "Normative Product Architecture." The other is called "Shipped Implementation." They're often different. The difference is the point.

Why the gap exists

If you're building AI infrastructure, the gap between your ideal architecture and your deployed architecture is probably wider than it is in any other category of software.

That's because the AI infrastructure landscape offers an unusually large number of theoretically correct choices that are practically premature. Kafka for event streaming. Qdrant or Pinecone for dedicated vector search. Celery for distributed task processing. A standalone recommendation service behind its own API gateway. Each of these is defensible on paper. Each of them also represents weeks or months of build time, operational overhead, and hiring pressure that most early-stage teams cannot absorb without stalling product delivery.

The result is a gap. The architecture you would build with unlimited time and a mature team is not the architecture you should ship with a five-person engineering org in its first year. That's fine. The problem isn't the gap. The problem is what teams do with it.

The dishonest pattern

Here's what usually happens: the engineering team ships the pragmatic version - a monolith, a simpler stack, batch jobs instead of streaming - and then marketing describes the north-star version as if it's already running. The pitch deck shows the microservices diagram. The architecture doc sent to prospects shows Kafka. The sales engineer describes the dedicated vector database.

Nobody is lying, exactly. They're describing the roadmap as the product. In most software categories, this gap closes fast enough that the misrepresentation is minor. In AI infrastructure, where the distance between "FastAPI BackgroundTasks" and "Celery with a dedicated worker pool behind Kafka" is measured in quarters, the misrepresentation compounds.

Two things go wrong. First, the engineering team starts feeling pressure to build toward the marketed architecture rather than the architecture the product actually needs next. Second, when an enterprise buyer's compliance team asks, "Where does our data live and what controls are in place today?" the team doesn't have a clean answer because the documented architecture isn't the deployed architecture.

The honest pattern

The fix is structural and boring: write both versions down, label them, and keep them current.

In our PRD, a major component like the recommendation engine has a "Normative Product Architecture" section that describes the target state - the heterogeneous graph neural network running in its own service, Qdrant for dedicated vector indexing, Kafka for real-time feature ingestion, a Celery worker pool for async training jobs. This is the architecture we're building toward. It's real. It has rationale and design constraints. It's not fiction.

Below it, the "Shipped Implementation" section describes what we actually deployed and the date it was current as of. For the recommendation engine, that means the ensemble model runs inside the FastAPI monolith. Vector search uses pgvector on PostgreSQL, not Qdrant. Training is triggered via FastAPI BackgroundTasks, not Celery. Cluster-safe scheduling uses PostgreSQL advisory locks, not a distributed queue.

Both sections are in the same document. Both are visible to the same audience. The gap between them is the roadmap - stated without embellishment.

What this discipline changes

Three things shift when you adopt this pattern.

Engineering decisions get cleaner. When the normative architecture is explicit, the team knows where they're going. When the shipped architecture is equally explicit, they know where they are. The distance between the two becomes a backlog - not an anxiety, not a debt narrative, not a vague sense of "we'll get there someday." It's a concrete set of migration steps, each with its own trigger condition: "We move from pgvector to Qdrant when our vector count exceeds N or our P95 query latency exceeds M." Deferred decisions aren't avoidance. They're engineering choices with documented criteria.

Each of those deferred decisions carries real value. We haven't built Kafka, Celery, or a dedicated vector service. That's not three items of technical debt. That's three quarters of engineering time we spent shipping product features instead - recommendations, contact scoring, the conversations workspace, the developer portal backend. Premature scale-out is the most expensive mistake in early-stage B2B SaaS architecture, and the shipped-vs-normative pattern is how you resist it without losing sight of where you're headed.

Customer conversations get more credible. Enterprise buyers don't trust vendors who describe everything as already built. They've been burned too many times. When a prospect's security team asks for an architecture diagram, we give them the shipped version - annotated with the normative direction and the conditions under which we'd migrate. That answer is so unusual in vendor evaluations that it builds more trust than the polished north-star diagram ever could.

The same transparency applies to compliance reviews. A SOC 2 auditor or a DPIA reviewer wants to know what's deployed, not what's planned. The shipped architecture section answers their question directly. The normative section answers the follow-up question they always ask next: "So what's your roadmap?"

Internal honesty compounds. This is the subtlest benefit and the most durable. When both versions are in the same document, it becomes culturally harder to conflate them. The marketing team can't accidentally describe the normative architecture as shipped because the PRD clearly labels which is which. New engineers joining the team can read one document and understand both the current state and the target state. Product managers writing feature specs know which infrastructure is available today and which requires a prerequisite migration.

Over time, this discipline produces a team that talks about its product accurately - not because accuracy is a virtue in the abstract, but because accurate self-knowledge makes every downstream decision better.

A template you can use tomorrow

If you want to adopt this pattern, the structure is six lines per component:

## [Component Name]

### Normative Product Architecture
[Describe the target-state architecture, its rationale, and the constraints it satisfies.]

### Shipped Implementation (as of [DATE])
[Describe what is currently deployed, what is deferred, and the trigger conditions for migration.]

That's it. No special tooling. No process change. Just a commitment to writing both versions down, in the same document, where the team, the customer, and the investor can see both.

The date stamp on the shipped section is critical. Without it, the shipped section becomes stale and the gap between the two sections becomes invisible again - which is exactly the problem you're solving.

The hardest part

The hardest part of this practice isn't the writing. It's the willingness to let the gap exist in a visible, labeled way. Founders want to describe the product they're building toward. Engineers want to describe the system they wish they had time to build. Enterprise sellers want to describe the architecture that wins the deal.

The gap between shipped and normative can feel like a confession. It isn't. It's a strategy. The companies that keep the gap honest build faster, sell more credibly, and make better architectural decisions than the companies that pretend the gap doesn't exist.

Write both versions. Label them. Keep them current. The gap is the roadmap - and the roadmap is the product.

What's the hardest architectural decision you've deferred and how did you document it? I'd like to hear what other teams are doing with this pattern.

#SoftwareArchitecture #ProductManagement #AIEngineering #BuildInPublic #StartupLeadership #DataArchitecture

The PRD Has Two Versions: What We Shipped and What We Will Ship