In some (ideal) cases the building block structure maps exactly to file-, package- or module structure of the source-code. But sadly that’s not always true.

Consider the following diagram: In the centre you find an excerpt of a file system, containing several .java and .php files. Left and right of this hypothetical directory listing you find two alternatives how to map these sources to architectural building blocks:

  • A_1 consists of x.java and y.java, A_2 of z.java and some php files, A_3 of g.java and h.java.
  • B_1 of x.java, y.java and z.java, B_2of all the rest

mapping code to blocks diagram

There can be good reasons for both versions. For your system, you should have specific reasons why certain building blocks contain which source code.

Mapping of building blocks to code is a specific decision

Although the mapping of code to building blocks should be aligned with file system structures, there might be cases where it’s completely different - some examples:

  • Somebody has accidently put too many files into the same directory
  • Several programming languages are mixed in the same source tree
  • Responsibility of building blocks has changed over time, but the corresponding source code files have not been moved around appropriately
  • Other constraints enforce a specific directory structure, e.g. some obscure frameworks require certain source files at specific locations, or the build-/deployment process expect certain directory structures, which don’t map to architectural building blocks.

Keep the mapping of code und building blocks straightforward

Try to keep that mapping simple and straightforward. Complex mappings, like the left version in the diagram above, should be avoided.

In ideal cases, directories in the file system are identical to building blocks. Contained blackboxes are then contained files in subdirectories…

See also