Service orientation is a pattern of the same level as object orientation or functional programming. It determines your basic unit of design. In OO, you basic unit is an object. In functional, it's a function. In service-oriented, it's a service and a contract. A service is a cohesive and isolated collection of operations. Every function in the service fits one high-level purpose, typically hiding one design descision. You should never have to look further than the service to completely understand the work that a service accomplishes. Thus, it is imparative to have clear and simple hand-offs to and from the service.
That is where contracts come in. They are the possible hand-off values of a service. If services represent function, contracts represent data. The simpler your contracts are, the less you are able to have un-expected ties between services, and the less likely you are to break isolation. As a rule of thumb, if you can't tell exactly what you can and can't do based on the the interface signature (and maybe a contract definition), it is too complex.
The key to understanding the code layout is a pattern called IDesign.
IDesign is a layered, service-oriented architecture pattern.
IDesign has five layers.
Clients - responsible for consumption of your program. For example, user interfaces, apis, windows services.
Managers - Organize the order of execution. These are the primary flows of your application
Engines - The algorithms, business logic, data-manipulation type stuff
Accessor - Abstract external resources for use by the application. For example, database access, file system access, external apis
Resources - Anything not controlled by your code (databases, external apis, etc). These are what accessors abstract.
Viewed in terms of orthogonality and information hiding, each layer is responsible for isolating/hiding a particular type of design concern.
Accessors - Third party code or components not fully in your application's control
Engines - Computation
Managers - Composition of functionality
Clients - Application representation and interaction
Layers may only call into the adjacent lower layer. (I.E. engines only call accessors, accessors only call resources). The one exception is that managers can call to both engines and accessors. Sometimes a client may call an engine, but it is rare that this is a good choice.
However, engines never call managers. That would mean your processing is calling your orchestration, which can lead to many unexpected execution order problems.
These simple rules categorize and organize the vast majority of programming responsibility types. The simple rules allow you to quickly find a piece of code and limit what other units of code it could be working with, thus reducing complexity.
By considering the few rules of IDesign, you are also led to follow other known best practices like SOLID, information hiding, stable dependencies and others.
One principle worth calling out specifically is single responsibility principle. IDesign draws attention to sneaky violations of single responsibility principle by differentiating responsibility types.
The folder structure reflects the primary responsibilities of IDesign, and other primary concerns like testing. It allows the solution to be more easily navigated and not have an overwhelming number of choices as the number of projects grows.
The numbers in the folders allow us to set the folder order to match the layering metaphor instead of being alphabetic.
The shared folder is for meta-infrastructure that is needed across projects. For example, dependency injection config, data contracts, and possibly logging. Do not be tempted to put app functionality in this folder.
Adding some namespacing to our projects (e.g. Accessors.Project or Tests.Project) allows our underlying file structure to be organized by responsibility type and easily navigated.