Readme - add some code architecture info

To provide an agreed path, a reminder for the existing team, a reference
for code-review, and an easier onboarding for future contributors.

README.md

@@ -56,3 +56,31 @@ Navigate to https://localhost:44345/ in a browser.
 #### Login
 
 Ask the team to make you a valid DfE Sign-in account with provider(s) associated with it.
+
+## Project architecture
+
+
+### Azure Function App Dependencies
+
+This project depends on multiple deployed Azure function app resources:
+
+* [dfc-providerportal-apprenticeships](https://github.com/skillsfundingagency/dfc-providerportal-apprenticeships)
+* [dfc-providerportal-courses](https://github.com/SkillsFundingAgency/dfc-providerportal-courses)
+* [dfc-providerportal-fileprocessor](https://github.com/SkillsFundingAgency/dfc-providerportal-fileprocessor)
+* [dfc-providerportal-findanapprenticeship](https://github.com/SkillsFundingAgency/dfc-providerportal-findanapprenticeship)
+* [dfc-providerportal-tribalexporter](https://github.com/SkillsFundingAgency/dfc-providerportal-tribalexporter)
+* [dfc-providerportal-ukrlp](https://github.com/SkillsFundingAgency/dfc-providerportal-ukrlp)
+
+### Project Structure
+
+#### Legacy
+
+The projects in the `Legacy` solution folder were inherited without good test coverage and are not in an easily testable state.
+
+#### WebV2
+
+New code is being written in the WebV2 project that is test-driven and uses modern patterns of development to achieve cleaner testable code.
+
+See the [WebV2 readme](src/Dfc.CourseDirectory.WebV2/README.md) for details of the patterns in use.
+
+The WebV2 controllers are made available under the legacy `Dfc.CourseDirectory.Web` project so that we can move routes across one at time. As such to run the WebV2 code you actually need to run the original "Web" project.

src/Dfc.CourseDirectory.WebV2/README.md

@@ -0,0 +1,41 @@
+# dfc-coursedirectory - WebV2
+
+## Patterns in use
+
+### MediatR / CQRS
+
+To achieve:
+
+* thin-controllers,
+* testability
+* separation of concerns
+* separation of testing from the aspnet infrastructure code
+
+we are using [MediatR](https://github.com/jbogard/MediatR).
+
+For an intro to MediatR in controllers see:
+
+* https://codeopinion.com/thin-controllers-cqrs-mediatr/
+    * [MediatR: Why should you use it? on YouTube](https://www.youtube.com/watch?v=yhpTZDavtsY)
+* https://codeopinion.com/fat-controller-cqrs-diet-simple-query/
+* https://ardalis.com/moving-from-controllers-and-actions-to-endpoints-with-mediatr/ 
+* https://jonhilton.net/2016/06/06/simplify-your-controllers-with-the-command-pattern-and-mediatr/
+* https://alexlindgren.com/posts/thin-controllers-using-mediatr-with-aspnet-mvc/
+
+### Tests
+
+There are no controller tests because the controller actions are very thin mappings.
+
+The tests are mostly integration tests that test an endpoint + behaviour, with things like CosmosDB calls mocked out.
+
+### Multi-page transactions - FormFlow
+
+To support stateful multi-page processes we are using the [FormFlow nuget package](https://www.nuget.org/packages/FormFlow/).
+
+### Folder Structure
+
+To keep things together that change together we are not using the traditional Views/Controllers folder structure. Instead we have `Features/*/` folders  that group together related functionality, including views, controllers and MediatR CQRS behaviour implementations.
+
+### Feature-per-file
+
+We are not doing class-per-file. Feature behaviour is implemented in a single .cs file following the MediatR query/command/handler patterns.