Code structure to handle multiple markets? (different business rules for every state in the USA)

Question

We're developing an app that has slightly different requirements for each business market (countries and states) that it's available from. It seems like a common situation but I can't seem to find a good article about structuring code/modules for this scenario.
It's a C# app and we're debating between Strategy vs Template patterns but there's also the consideration of folder structure and naming conventions. It seems like a separate project for each state would get unmanageable quickly (e.g. 5 core services X 50 state-custom projects) = 250 projects!!) Perhaps 1 custom project per service handling specializations organized in sub-folders per state?

Answer 1

Have a single app and design the appropriate configuration solution.

JacquesB hints at this, but I want to state it more strongly. You must do this by configuration rather than developing 50+ versions of the codebase. Anything else will be insanely unmanageable.

If there are complex requirements which can't be handled by simple configuration parameters, design a more complex configuration solution.

Your configuration might even have a simple scripting language that defines logic requirements. That is ok. The key is that the "configuration" must be cleanly separated from the codebase of the app.

Otherwise, things like identifying and fixing bugs will be a mess. With normal versioning in addition to locale-specific versions, you will have hundreds of versions in the field. And you won't be able to easily tell whether a bug is related to the locale-specific code or the base code.

Start thinking about edge cases now.

This is a situation where there is a high risk of making bad assumptions that will be incredibly costly. Such as "Each app user will only ever need to operate within one locale." Is that true? Make sure you think really hard about such issues as early as possible.

Answer 2

It really depends on what is different. Is it something which can be expressed purely by configuration (eg. tax rates), or do you really need separate code logic for each state? The more you can handle purely by configuration the better!

You most likely does not need separate code by state. For example you mention that some markets issue refunds while other issue replacements. This is still only two code paths you need to test. Then you can have a configuration indicate which path should be used for which state. This is much better that having separate code for each state. You still only need to test two code paths rater than 50.

If you ever feel the need to write individual code for each of 50 states, you are probably doing it wrong. You should definitely not have separate projects per state, or even having "50 different" of anything except configurations sections.

Answer 3

I've had some practical experience with such projects, and can at least offer some general guidelines.

• JacquesB is absolutely right that configuration is your bestest friend. Whether you put that configuration in files or in database tables is a stylistic choice (though I'd be leaning towards config files, since once you get a service set up, I'm willing to bet it won't change much).

• Expect code that looks a lot more indirect than what you're probably accustomed to. There will be many places where instead of saying "Do this next," you'll be saying "Ask the config for what we're supposed to do next, then go do that". Which can be a development headache, but you'll get used to it.

• I'd recommend a structure of "These are the common elements that everybody probably wants, and these are the bespoke elements hand-designed for individual states." To that end, correctly identifying that default functionality will be a big part of how easy/awful the code is to work with in the future. Be prepared to do some refactoring when you learn that more stuff than you thought needs to be configurable.

• Always make sure that any error messages coming from the custom elements identify exactly where they came from. The huge number of different execution paths mean that debugging will suck no matter what; anything you can do to reduce the amount of easter-egg hunting will be more than worthwhile.

• Invest the time to make a good automated test suite. A REALLY good automated test suite. This is always good practice, but for you, it could literally mean the difference between success and failure. Again, it's the huge variety of execution paths; any modifications to the common code will leave you vulnerable to butterfly-effect bugs in branches you weren't expecting. You need to catch those bugs before they hit production.

Answer 4

Although config can help its not going to solve all your problems an it may create new ones.

By far the best way in my experience is to create a multi tenancy solution which can handle all or any of the states(tenants)

This will require configuration. ie sales tax percentage by state but also conditional code LegalMethodOfCalculatingWorkingHoursA vs B

If your app is hosted/online you could take microservices approach to the conditional code but an off line solution will have to bundle all the optional modules and select between them

You will find some modules reused across all states, such as sales tax and some crazy law ones only used in a single state. You will also find that laws change over time. so the modules used will vary by time within a single state

So I would go with naming by functionality rather than state.