Architectural examples: how does your app fit together?

I had the pleasure of hearing a talk by Stewart Baird today, and I liked one of his ideas so much I thought I’d mention it here.

Object-relational mappers, IoC, ESBs, REST etc are all a big deal when you’re introducing them to teams or working with contractors who haven’t used them before.

To explain how it all fits together, you should create an architectural example — a reference system that implements a single, simple behaviour. To be effective, it should:

Be end-to-end. It should demonstrate how events and data flow from the user interface through to the database and back, including any and all services in between.
Be checked into source control. Publish it alongside the production code so everyone can see it.
Lead your production code. When you introduce a new component — e.g. a distributed cache — add it to the architectural example first, before rolling it out to your main system.

It’s always nice if you can explore and see everything working for yourself. An architectural example can help explain new topics to less-experienced developers, and provide a nice reference of how you want to see things implemented in future.

I can’t decide if this is an application service, or a domain service!

Deciding whether a service belongs in the domain or service layer can be a very tough question.

I think it’s important to remember that, just because a class:

Deals exclusively with objects in the domain model

Is called in turn by other application services

Has no dependencies on other non-domain services

…does not make it a domain service.

Try not thinking of it as the domain layer, but as the domain model. The domain model is a very strict abstraction of the business; domain layer is just a tier in your app where the model resides. It’s a small change of words but a big difference in perspective.

Is your service actually part of the domain model, or just manipulating it?