Improve architecture docs to dig a little deeper into 'how'

[TimMonko]

📚 New content request

Without a comp sci background, I have been relying on the docs to understand how to navigate the structure of the code base. The architecture guide has been immensely helpful, but I've noticed (and will continue to edit this) a few shortcomings. At the 2025/01/15 community meeting, I was given an excellent explanation by @Czaki and @brisvag on how to link up what I was confused about, and I think this is appropriate for new content in the docs.

My primary issue was figuring out how napari models/events get connected to vispy. One reason for this is a lack of type annotations in multiple _vispy modules, for which I will link a relevant issue in napari/napari. But here is my current analysis of the architecture docs:

Strengths

1. Describes effectively why backends (Qt, Vispy) are separated.
2. Describes effectively why napari evented models exist.
3. Describes excellently how napari models exist and how events are used.
4. Describes how a backend might use napari events

Weaknesses

1. Does not explain how backends are instantiated in the sense that it is unclear when and what glue code hooks up napari models to Vispy and Qt.
2. Does not explain how napari gets instantiated generally, what are all the connections between the code. I know they are connected, some of the pieces of those connections (i.e. models talk to vispy), but it really doesn't explain the ordering of the connections.

Outline / Suggestions

Either as new pages in the architecture guide (my preference) or added to napari models and events

1. Provide an example that walks through the links of the architecture. For example, ScaleBarOverlay exists in components and gets passed to VispyScaleBarOverlay (again type annotations needed here). What's in between includes ViewerModel and... at least visual.py. We, in a round about way, did this at the community meeting and it significantly improved my understanding of napari's bones.
2. Maybe an example doc describing what happens when someone types napari into the terminal. I think this would help understand the roots, trunk, and branches of napari tree. This took me a while to figure out how and in what ways each module talks to the other modules. The models/events and directory organization docs do a pretty good job of this, but are just missing that final linking of everything up.
3. More detail on how exactly Vispy works (node, viewer, overlay, etc) and is shared across the many modules. (I edit this to say that it is not immediately clear that napari models and their events are used to override certain elements of vispy visuals --which is cool functionality btw)
4. More details on how exactly to understand how and why something like _app_model and _qapp_model exists and is differentiated (is it just necessity? something else?)
5. Improved type annotations will really help with all of this too!

[DragaDoncila]

Just wanted to drop by and thank you for this awesome summary and the great suggestions @TimMonko. I especially agree that some flowcharts or sequence diagrams of "what happens when you type napari into the terminal", would be super helpful. @lucyleeow and I have had to go back through the code many times to relearn this 😆