Architecture Guidelines

Some proposals for guidelines based on things I've seen recently, and over the years:

# Project documentation:
1. All projects should have a README file in their repository root that includes the following information, or contains links or instructions on where to find the following information:
1. How to setup a local development environment for working on the project, including:
1. Prerequisite installed software (IDEs, SDKs, Databases, other tooling, recommended IDE extensions, etc.), including version requirements.
1. How to open the project in the recommended IDE/editor (e.g. "Open the .sln file in the repository root with Visual Studio 2019")
1. How to build and run the project, including:
1. How to restore any packages that aren't automatically restored. For example, Nuget packages are auto-restored by `dotnet` tooling, but `npm` packages are not.
2. How to obtain a local copy of any required database, if necessary.
1. How to run the project's tests
1. How to contribute to the project's tests, including a brief summary of the different types of testing that are utilized in the application (unit testing, integration testing, UI testing, etc).
1. How to contribute changes to the primary branch of the project, including a description of branching strategy, the project's pull request process & requirements, any review processes the project is subject to, including code reviews, architecture review, security reviews, etc.
1. How the project is deployed, including:
1. A description of each environment that the project may be deployed to
1. Any URL(s) where the deployed/published project may be found
1. A description of the process for promotion from one environment to another, including necessary approvals, manual testing/verification, and actual actions that must be taken to achieve the environment promotion (e.g. release pipelines).

1. All possible sources of application configuration that is environment-dependent MUST be clearly enumerated in a README file in the root of the project's repository, or must otherwise be linked to from such a README file. This file MUST be updated when changes are made to how an application is configured.
1. Possible sources of configuration include, but are not limited to:
1. Injection by an automated build or release process
1. Stored on a cloud service, such as Azure App Service configuration (injected into the app via Environment Variables), or Azure Key Vault
1. Stored in database table(s)
1. Stored in files checked into the repository, including appsettings.*.json, launchSettings.json, package.json, app.config, and any other file containing configuration.
1. Stored from predefined files/directories in environments where the application is running.
1. Hardcoded configuration (DO NOT use hardcoded configuration, but if it truly cannot be moved elsewhere, please document it.)
1. Possible types of configuration include, but are not limited to:
1. Any credentials, including username/password pairs and API keys
1. Any configuration the instructs the application how to locate an external resource, including database connection strings, URLs, IP addresses, email addresses, cloud provider subscription IDs, resource IDs, or any other external resource.

# General Architecture:
1. Utilize Dependency Injection in all projects whenever possible _This probably needs to be expanded upon - its maybe too open-ended and vague_
1. In projects utilizing dependency injection:
1. DO NOT store global singletons in static fields/properties. Always resolve such objects from the DI container, including services, configuration, or any other singleton.
1. DO NOT manually instantiate classes that are registered with the DI container. This is especially applicable to Entity Framework `DbContext` instances, because manual instantiation implies that the `DbContextOptions<>` are also being manually created, are hardcoded into the `DbContext` constructor, or are being stored as a global singleton.
1. Exception: Instantiating `DbContext` instances during setup when the instance is being configured with some an in-memory provider.
1. AVOID using the service locator pattern, PREFER using the standard mechanisms of injection provided by your DI framework (e.g. constructor injection, ASP.NET Core parameter injection via `[FromServices]`, etc.)

# Web Application Architecture:
1. When an application needs to run long-running or recurring background jobs, you SHOULD prefer Hangfire (https://www.hangfire.io/) over homegrown out-of-process job engines, manual spawning of threads, using `Task.Run`, or utilizing a cloud-native solution.
1. Exceptions may be made if:
1. The principal purpose of the web application is to spawn, facilitate, manage, execute, or monitor such background jobs, or
1. Running background jobs in the same process as the web application will cause significant performance, stability, or security issues.
1. DO NOT write business logic in controller classes. DO write business logic in service classes that do not have any concerns or knowledge of web requests & responses. Such classes can be directly tested with unit tests, can be easily called from other services classes to facilitate code re-use and consistency.