Document high level project responsibilities

[Al12rs]

The Problem:

The solution is divided into many separate projects but it is often hard for outsiders to get a clear idea of what each project's responsibility actually is.

In particular the following projects could benefit from some clarifications:

• Abstractions (what should go in here, what shouldn't?)
• Common (what are the differences with Abstractions, how to decide which one to use?)
• App (clarify business logic should not be in here)
• App.UI (clarify how much logic should be in here and how it interacts with the rest)
• DataModel (what should not go in here)

Defining these clearly is important to allow developers to know the scope of each project, to avoid the introduction of unwanted dependencies, scattering of business logic across various parts of the application, misplacement of new code, etc... This counts for existing developers as well.

It also saves time to new developers, that don't need to go into the code to figure out whether it is interesting or relevant to what they are working on.

Solution:

My idea would be to add a concise Readme.md markdown file to each project folder and potentially to some namespace folders, but I'm open to alternatives, especially if they are more visible from IDEs for example.

Some for some projects some discussion/clarification between the team on the exact responsibilities might be required.

[Al12rs]

The code base has now been split into a high number of projects, for the purpose of achieving a high level of abstraction and avoiding circular dependencies between the various components.

This decision and the general approach should be documented as a page in our App documentation.

This should be on top of adding a short Readme.md to each project folder indicating what the project contains and the purpose. Investigate if/how to make these show up in IDE.

Tasks:

• [ ] Add Abstraction approach guideline Doc page
• [ ] Add Readme.md to each project folder.