How to Design Robust Service‑Oriented Architecture and Tame Legacy Code

Introduction

Design (Software Design) and Architecture (Software Architecture) serve different purposes: designers focus on component‑level details, while architects consider the macro structure between components. Good designers become architects, but not all designers achieve architectural depth.

Basic Principles of Service‑Oriented Architecture

When building a new system from scratch, aim for minimal historical baggage, simple context, and low design constraints, while ensuring each new line of code does not become tomorrow’s burden.

Step‑by‑Step Process for a New Service

Abstract the "surface" to discover the underlying "core" by analyzing common features across scenarios.

Materialize the core as a domain model, separating it from the persistence model and SPI‑ifying the tunnel.

SPI‑ify dependencies within the domain model to decouple external systems and invert control.

Mock all SPI implementations and ensure unit tests for the core domain model pass.

Implement the TUNNEL BUNDLE: design the persistence model focusing on storage and retrieval.

Implement the dependency SPI adapter bundle to connect real services.

Wrap domain services, keeping them model‑centric and business‑agnostic.

Compose domain services into scenario bundles or business SOPs according to requirements.

Working on Legacy Systems

Coding on legacy code is painful; common excuses include poor code quality, architectural flaws, and perceived lack of ownership. Effective refactoring follows the principles from Michael Feathers' "Working Effectively with Legacy Code".

When to Refactor

Code is so degraded it cannot be maintained or new features are costly.

Current technical architecture cannot support upcoming business growth.

Obsolete features remain entangled with useful code.

Business logic is scattered across unclear boundaries.

Future‑proof planning and new technology adoption are needed.

Leadership changes require new flags.

Key Architectural Practices

Focus on upstream call convergence, decouple downstream dependencies, switch services by unit, and gradually decommission legacy systems.

Decommissioning Legacy Systems

Keep the old implementation as the default API, introduce the new implementation as a fallback, and route a portion of traffic to it.

Gradually move business‑critical features to the new implementation, making it the default while the old version becomes a downgrade path.

After stable operation, switch all defaults to the new implementation, retaining the old version as an emergency downgrade.

Thus, each deployment can roll back instantly by reverting to the previous successful version.

Conclusion

The article summarizes a methodology for building and refactoring service‑oriented systems using NBF’s remote polymorphism and orchestration capabilities, offering practical guidance for teams facing architectural and code‑decoupling challenges.