Architecture.md

Architecture

Notes about I'd architecture a new long-life project.

TL;DR

1. Monolith first, split when needed.
2. Folder structure by feature, component, or service. Avoid layers, file category, or same class.
3. Place tests along code. Don't use a separate folder
4. Avoid long nested paths for endpoints. Context should be in the JWT
5. Composition over inheritance
6. Promote dependency injection
7. Use docker for development at least
8. Use built-in tools first, avoid third party tools (e.g. test runners, linters, formatters, etc.)
9. Use middleware based web framework
10. Use middlewares as core of your req/res processing, not just for pre/post hooks
11. Avoid build steps when possible
12. Take advantage of the power of SQL and RDBM, when needed use JSON type for dynamic content
13. Use libs that promotes Unix and Web standards
14. Use HTTP2/gRPC
15. Do not silent errors, log them at least
16. Avoid ORMs; queries become suboptimal pretty quickly. SQL is a standard, ORM APIs aren't
17. Use early returns pattern
18. Tests must be idempotent. They should not depend on previous tests, assertions should not depend if DB was emptied or not.
19. Use gRPC for private APIS, use REST for public APIS
20. For tests, use a library to create fake random data.
21. Ready to run in local
22. Do not remove database and shutdown containers after tests. Do it in setup.
23. Place OpenAPI definition along endpoint handlers
24. Code monolith, deploy microservices when needed. Developing, maintaining and debugging microservices is hard but k8s is great.
25. ENV variables must default to values ready for Production. Overwrite them for other envs (CI, test, developemnt, etc..)
26. Write tests in the same programming language than your project.
27. Apply emergent architecture of your application rather than using MVC by default. MVC leads to anemic domain model.
28. Program to interfaces not implementations
29. Do not expose model details in your public endpoints. For instance, hide model details such as /book/isbn10/:id & /book/isbn13/:isbn, use /book/:isbn instead.
30. Do not code tests as set of use cases within arrays or sets. They need to run in a loop, that's the test runner job.
31. If you are developing a web service with a modern framework, do not pursue code coverage with unit tests. Execise your service trough available endpoints.

TBD