Create `ARCHITECTURE.md`

[simonsan]

Should be describing certain architectural decisions and giving a graphical overview.

One of the lessons I’ve learned is that the biggest difference between an occasional contributor and a core developer lies in the knowledge about the physical architecture of the project. Roughly, it takes 2x more time to write a patch if you are unfamiliar with the project, but it takes 10x more time to figure out where you should change the code. This difference might be hard to perceive if you’ve been working with the project for a while.

I find the ARCHITECTURE file to be a low-effort high-leverage way to bridge this gap. As the name suggests, this file should describe the high-level architecture of the project. Keep it short: every recurring contributor will have to read it. Additionally, the shorter it is, the less likely it will be invalidated by some future change. This is the main rule of thumb for ARCHITECTURE — only specify things that are unlikely to frequently change. Don’t try to keep it synchronized with code. Instead, revisit it a couple of times a year.

• bird’s eye overview of the problem being solved
• specify a more-or-less detailed codemap
  • answers: where’s the thing that does X?
  • answers: what does the thing that I am looking at do?
  • A codemap is a map of a country, not an atlas of maps of its states.
  • Use this as a chance to reflect on the project structure.
  • Are the things you want to put near each other in the codemap adjacent when you run tree .?
• describe coarse-grained modules and how they relate to each other
• avoid going into details of how each module works, pull this into separate documents or (better) inline documentation.
• Do name important files, modules, and types.
• Do not directly link them (links go stale).
  • Instead, encourage the reader to use symbol search to find the mentioned entities by name. This doesn’t require maintenance and will help to discover related, similarly named things.
• Explicitly call-out architectural invariants. Often, important invariants are expressed as an absence of something, and it’s pretty hard to divine that from reading the code.
• Point out boundaries between layers and systems as well. A boundary implicitly contains information about the implementation of the system behind it. It even constrains all possible implementations.
• After finishing the codemap, add a separate section on cross-cutting concerns.

https://matklad.github.io/2021/02/06/ARCHITECTURE.md.html

Examples:

• https://github.com/rust-lang/rust-analyzer/blob/master/docs/dev/architecture.md
• https://github.com/lemunozm/mailfred/blob/main/docs/architecture.md
• https://github.com/helix-editor/helix/blob/master/docs/architecture.md

[simonsan]

Project Architecture Questions

1. Project Overview:

   • What is the primary goal of your project?
   • What problem does it aim to solve or what functionality does it provide?

2. Architecture Overview:

   • Can you briefly describe the overall architecture of your project?

3. Components:

   • What are the main components or modules of your project?
   • How do these components interact with each other?

4. Technology Stack:

   • What programming languages and frameworks did you use for your project?

5. Data Storage:

   • Does your project require any databases or external data storage?
   • If yes, what type of databases do you use, and how do you manage data storage?

6. APIs and External Services:

   • Does your project interact with external APIs or services?
   • If yes, how do you integrate and handle these interactions?

7. User Interface (UI):

   • Does your project have a user interface?
   • How is the UI structured and designed?

8. Architecture Patterns:

   • Have you used any specific architecture patterns (e.g., MVC, MVVM, etc.) in your project?
   • If yes, where and why did you choose to apply these patterns?

9. Security:

   • How do you handle security concerns in your project, such as authentication and data protection?

10. Deployment:

    • How is your project deployed in production or testing environments?
    • Do you use any containerization or orchestration tools (e.g., Docker, Kubernetes)?

11. Scalability:

    • How does your project handle scalability? Is it designed to accommodate growth in the user base or data volume?

12. Testing:

    • Do you have a testing strategy in place for your project?
    • What types of tests do you perform (e.g., unit tests, integration tests)?

13. Documentation:

    • How is the documentation for your project organized?
    • Do you have any automated documentation generation tools integrated?

14. Continuous Integration and Continuous Deployment (CI/CD):

    • Do you have a CI/CD pipeline set up for your project?
    • How do you manage code integration, testing, and deployment?

15. Error Handling:

    • How do you handle errors and exceptions in your project?
    • Do you have logging mechanisms to track issues?

16. Performance Optimization:

    • Have you implemented any performance optimization techniques in your project?

17. Code Structure and Organization:

    • How is your codebase structured and organized?
    • Do you follow any specific coding guidelines or principles?

18. Contributing to the Project:

    • Do you have guidelines for others who want to contribute to your project's development?