Add an ARCHITECTURE.md to the repo

[PrototypeNM1]

Currently it is difficult to get a "big picture" understanding of Bevy's code base. Adding an ARCHITECTURE.md - described by Maklad here - would be a good first step toward providing mental scaffolding.

This was previously brought up in the CONTRIBUTING.md issue.

[alice-i-cecile]

I'm not entirely convinced this should exist. It's hard to maintain, high visibility and requires a lot of expertise to write.

What would you want to see in this?

[Nilirad]

I gave it a look, and it looks like that it's so high level that it doesn't require constant maintenance. I'm not particularly convinced to put it as a separate piece of information. I would rather include it in elsewhere. I think the bevy crate-level documentation would be a not perfect, but good place.

[alice-i-cecile]

I prefer that. I would also like to make sure we have good READMEs for each of the non-standard folders in the repo, and eventually eliminate the top level docs folder completely.

[Nilirad]

I would also like to make sure we have good READMEs for each of the non-standard folders in the repo

Maybe crates/README.md could be used to give a bird's eye view of the architecture of the codebase, like rust-analyzer does with ARCHITECTURE.md

[alice-i-cecile]

I think that's a nice place for that information :)

[Nilirad]

Also a nice excuse to put the bevy crate in that folder too 😏
I think an issue/PR was opened at least once about that.

[PrototypeNM1]

What would you want to see in this?

A code map is the important part. What are the workspaces, how are they tied together, what's making them tick (at a high level).

Maybe crates/README.md could be used to give a bird's eye view of the architecture of the codebase, like rust-analyzer does with ARCHITECTURE.md

This would probably work. The key points are this should be maximally discoverable and should form a basis to which an understanding of Bevy can start being hung off of. I think a good example of the target specificity would be Blender's code layout and directories explained.

[Nilirad]

The Blender code layout just gave me the idea that we could have a diagram of all the in-engine plugins all grouped by feature.

Another thing that can be taken is the layered approach: core, reflect and tasks on the bottom; ecs and app in the middle; and all the plugins on the top.