Advertise with Us|Sign Up to the Newsletter

Real systems require service discovery, API gateways, centralized configuration, and built-in resilience. In this live, hands-on workshop, you’ll build a working microservices system end-to-end, define service boundaries, wire up discovery, configure a gateway, and handle failures properly.

Welcome to this week’s issue of WebDevPro.

This issue looks at a common transition in modern engineering: taking a fast proof of concept and turning it into something that can survive real change.

Consider a small internal AI support chatbot. The architecture is simple. A React frontend collects messages and sends them to an Express POST /api/chat endpoint. The server returns a short reply. The goal here is speed, not durability.

To move quickly, the frontend stores messages as any[]. The backend reads req.body.messages from untyped JSON and returns a response like:

{ "reply": "You said: hello" }

There is no formal contract between frontend and backend. The agreement lives in shared understanding: reply is a string, and messages is an array of objects with role and content. When both sides are written close together, this feels stable.

Then the requirements change.

The reply must now include structured data: the assistant’s message, references, and follow-up questions. The backend evolves and begins returning an object under reply instead of a string. The frontend does not change. The build passes. The browser fails at runtime because React attempts to render an object as if it were a string.

Nothing in the type system flagged the mismatch because nothing at the boundary defined what the response was supposed to be.

This is where TypeScript either acts as a safety mechanism under change or becomes a thin layer of annotations. What follows is a practical look at how that same chatbot evolves into a production-safe system by making contracts explicit and boundaries deliberate.

The chatbot did not break because the change was complex. It broke because the change was invisible to the type system.

On the frontend, state was typed as any[]. The API response was treated as whatever res.json() returned. On the backend, req.body was used without an explicit shape. From TypeScript’s perspective, there was nothing concrete to compare, so the change in response structure did not register as a problem.

The fix was not adding defensive conditionals in the UI. It was introducing a shared domain contract and making both sides depend on it.

Instead of allowing the frontend and backend to “just agree,” the system defines explicit types for:

These types live in a shared module that both the frontend and backend import. The frontend state becomes ChatMessage[]. The API call returns Promise<ChatResponse>. The backend handler constructs a value that must satisfy ChatResponse.

At that point, the contract stops being an assumption and becomes code.

If someone changes the shape of reply again, the compiler will force every dependent piece of code to reconcile with that change. The mismatch that previously appeared in the browser now appears during build.

In practical terms, this shifts the feedback loop. Instead of discovering drift during manual testing or after deployment, the team discovers it the moment they try to compile. That difference seems small, but over time it fundamentally changes how safely a system can evolve.

Introducing shared types stabilizes collaboration between frontend and backend. It does not solve everything.

There is still one place where untyped data enters the system: the network boundary.

On the backend, req.body arrives as raw JSON. On the frontend, res.json() returns data that TypeScript cannot inspect at runtime. Even with shared contracts, the system is still trusting external input.

In the chatbot’s case, this matters more as the system grows. Deployments may not always be perfectly synchronized. A proxy or middleware layer might alter payloads. A partial rollout could temporarily mix versions of frontend and backend.

Shared types alone cannot guard against that.

The practical adjustment is simple but important: treat boundary data as unknown until it is validated.

Instead of assuming that req.body matches ChatRequest, the backend checks that it actually does. Instead of assuming that res.json() returns a valid ChatResponse, the frontend verifies the shape before proceeding.

These checks do not need to be elaborate. Lightweight type guards are enough to confirm that required properties exist and have the correct types. Once the data passes that validation step, the rest of the system can rely on strong typing with confidence.

This introduces a clear separation of responsibilities:

In day to day development, this prevents subtle corruption. Rather than allowing malformed data to move deeper into the UI or business logic, the system fails immediately at the edge. Errors become explicit and local instead of diffused and harder to trace.

The chatbot remains small, but its architecture becomes more deliberate. The boundary is no longer a blind spot; it becomes a controlled entry point.

As the chatbot matures, another requirement arrives: support more than one LLM provider.

This is a common inflection point. Early on, it is convenient to wire the backend directly to a single SDK. The response from the provider flows straight through the server and into the UI. It feels efficient.

It also quietly couples your entire stack to a vendor’s response shape.

If that vendor changes its format, or if you decide to introduce a second provider, the ripple effects can reach the frontend quickly. What began as a backend integration detail becomes a full-stack coordination problem.

In the chatbot’s evolution, this risk is handled differently. Instead of exposing raw provider responses, the system defines a provider interface that returns a domain-level ChatReply. Each provider implementation adapts its own SDK response into that shared shape.

The rest of the application does not know or care which provider generated the reply. It only understands the domain contract.

This decision seems architectural, but it has very practical consequences. Switching providers or introducing a second one no longer forces a redesign of shared types. The volatility is contained. The surface area of change is smaller.

TypeScript reinforces this separation. The compiler ensures that every provider implementation produces a valid ChatReply. The backend handler depends on the interface, not on vendor-specific JSON.

In a growing system, this is what stability looks like. The parts that are likely to change are isolated behind clear contracts. The parts that need to remain steady, especially the frontend, are shielded from that churn.

Feature growth rarely stops at integration. The chatbot evolves again. Sometimes a response includes citations. Sometimes it does not.

A quick solution would be to add optional fields. Over time, optional fields accumulate. The type becomes flexible, but also ambiguous. It becomes unclear which combinations are valid and which are accidental.

Instead, the chatbot models these variations explicitly using a discriminated union. A response is either a plain answer or an answer with citations, and the kind field identifies which one it is.

On the frontend, rendering logic switches on that kind. The exhaustive check ensures that every variant is handled.

This design choice has a subtle but important effect. When a new response variant is introduced later, the compiler highlights every place that must adapt. Nothing slips through unnoticed.

In everyday development, this reduces the risk of partial updates. The type system becomes a guide for refactoring, not just a static annotation layer.

The chatbot still feels small. The difference is that its possible states are no longer implied. They are declared.

As the chatbot grows, new endpoints appear. Health checks. Admin actions. Maybe analytics or feedback capture. The API surface expands gradually.

This is usually where small shortcuts start accumulating.

A common one looks harmless:

const data = (await res.json()) as ChatResponse;

The cast makes the compiler quiet. It also shifts responsibility back to the developer. At the exact point where the system is most exposed to incorrect data, you are asserting that everything is fine.

In a small codebase, this feels manageable. In a growing one, these assertions multiply. Over time, they erode the safety you thought TypeScript was providing.

In the chatbot’s evolution, this problem is addressed structurally rather than procedurally. Instead of scattering casts, the system defines a mapping between route literals and their request and response types. The endpoint determines the shape. The generic client enforces it.

Now the type of /api/chat is tied directly to ChatRequest and ChatResponse. You cannot accidentally call the wrong endpoint and pretend it returns something else. The compiler resolves the relationship based on the route itself.

This removes a category of silent drift. It also makes the API surface self-documenting. When someone adds a new endpoint, they define its contract in one place, and the rest of the system aligns automatically.

It is a small shift in structure, but it prevents gradual type erosion.

The chatbot still answers questions. The UI still renders messages. The architecture is not radically different from the initial proof of concept.

What changed is where mistakes surface.

At first, mismatches appeared in the browser.
After shared contracts, they appeared during compilation.
After boundary validation, they appeared at the edge of the system.
After isolating providers, vendor changes stopped leaking across layers.
After modeling variants explicitly, feature growth became safer.
After tightening endpoint typing, unsafe assumptions stopped spreading quietly.

None of these changes required advanced language features. They required clarity about boundaries and discipline about contracts.

In a system that evolves under real-world pressure, assumptions are the most fragile dependency. TypeScript is most valuable when it turns those assumptions into enforceable structure.

The chatbot did not become more sophisticated for its own sake. It became more predictable under change.

For a deeper exploration, pre-order Clean Code with TypeScript. The book takes a detailed look at the evolving chatbot system and walks through the architectural decisions, trade-offs, and production considerations behind it.

If you’re a PacktPub subscriber, you can access the Early Access version right away.

Refactoring production systems is risky, especially when API changes and hidden coupling are involved. In this Deep Engineering session, learn how to safely evolve real-world codebases using ast-grep and Claude Code, with practical guardrails you can apply immediately.

Use code WDP40 to get 40% off your seat.

🛡️ Zod Makes Runtime Validation Feel Native to TypeScript

If you’ve ever trusted req.body a little too much or written as SomeType just to quiet the compiler, you already know the pain: TypeScript disappears at runtime. The type system keeps you safe inside your codebase, but JSON at the network boundary remains unchecked.

Zod solves that gap cleanly. It’s a TypeScript-first schema validation library that lets you define runtime validation and static types in one place. You describe the shape once, validate incoming data against it, and automatically infer the TypeScript type. No duplication. No drift between interface and validator.

The real value shows up under change. When your API evolves or a provider shifts its response format, Zod forces the mismatch to surface immediately at the boundary instead of leaking deeper into your system. It turns assumptions into enforced contracts.

Good architecture is often about making edges explicit. Zod gives those edges structure.

That’s all for this week. Have any ideas you want to see in the next article? Hit Reply!

Cheers!

Editor-in-chief,

Kinnari Chohan