Microservice Architecture for Contract Management: Challenges, Strategy, and the Stencil Framework

Facing rapid business growth and an outdated .NET contract management system that could not meet throughput, stability, or scalability requirements, the company experienced high contract processing costs and a lack of expertise for the legacy code.

To address these issues without interrupting ongoing business, the team adopted a step‑by‑step strategy: expose functional service interfaces around the existing system, use those interfaces as proxies to decouple callers, iteratively decompose the monolith into independent services, and eventually replace the old system with newly built microservices.

Microservices are defined as small, single‑purpose services that run in independent processes, communicate via lightweight protocols such as JSON or XML, and are loosely coupled so that changes to one service do not require redeploying others.

The architecture brings several benefits: heterogeneous technology choices for different business needs, independent testing and deployment that reduces risk, fine‑grained scaling, fault isolation, alignment with Conway’s law for full‑stack teams, and overall improved maintainability.

To accelerate microservice development, the team created Stencil , a Ruby‑based framework consisting of four parts: a Stencil template library, a code‑generation tool, a continuous‑integration (CI) template, and a one‑click deployment tool.

The Stencil template is a standalone Ruby project containing code templates (using Webmachine, RSpec, and Rake tasks) and configuration templates for NewRelic, Passenger, Nagios, Apache, and Splunk. It also provides diagnostic URLs such as /diagnostic/, /diagnostic/version, /diagnostic/config, etc.

[
    {"rel": "index", "path": "/diagnostic/"},
    {"rel": "version", "path": "/diagnostic/version"},
    {"rel": "config", "path": "/diagnostic/config"},
    {"rel": "hostname", "path": "/diagnostic/hostname"},
    {"rel": "heartbeat", "path": "/diagnostic/status/heartbeat"},
    {"rel": "nagios", "path": "/diagnostic/status/nagios"}
]

The code‑generation tool lets developers create a runnable microservice project quickly, with options such as --name, --git-owner, --database, --triggered-task, --provider, --consumer, --branch, and --face-palm for name validation.

Create a project from the stencil template (version 0.1.27)
    --name, -n <s>:   New project name. eg. things-and-stuff
    --git-owner, -g <s>:   Git owner (default: which team or owner)
    --database, -d:   Include database connection code
    --triggered-task, -t:   Include triggered task code
    --provider, -p:   Is it a service provider? (other services use this service)
    --consumer, -c:   Is it a service consumer? (it uses other services)
    --branch, -b <s>:   Specify a particular branch of Stencil
    --face-palm, -f:   Override name validation
    --help, -h:   Show this message

The CI template, built on Bamboo, defines three stages: packaging (run unit and integration tests, then build an RPM), publishing (push the RPM to Koji and create an AMI with Packer on AWS), and deployment (launch the specified AMI in acceptance or production environments).

For one‑click deployment, the team uses Asgard, a web‑based AWS management tool, to create resources, define applications and clusters, and integrate load balancers, EC2 instances, and auto‑scaling groups. A simple command line tool wraps Asgard functionality: asgard-deploy [AppName] [AppVersion] After five months, the contract management system was rebuilt as a collection of independent microservices handling products, pricing, sales, signing, review, and PDF generation. Each service has an owner and integrates with Page Duty for alert notifications, enabling rapid issue response.

In summary, by adopting a microservice architecture and the Stencil framework, the team successfully decomposed a monolithic legacy system into loosely coupled, easily scalable services, shortened development cycles, and improved operational agility.

References:

http://martinfowler.com/articles/microservices.html

http://jaxenter.com/cracking-microservices-practices-50692.html

http://microservices.io/patterns/microservices.html