docs: improve architecture diagram

[laurenceisla]

Does the following:

• SVG format instead of PNG
• The components now have links to the source code their reference in the Docs
• Supports dark mode

[wolfgangwalther]

Fantastic stuff.

Do you think there is any way to make the background transparent in both svgs instead of a sliiightly different color than readthedocs uses?

[steve-chavez]

Looks awesome!

One thing though, should we have links in the arch diagram to the components or to the reference docs?

If we did it that way, we could also link:

• Proxy -> https://postgrest--3592.org.readthedocs.build/en/3592/explanations/nginx.html
• Authorization -> https://postgrest--3592.org.readthedocs.build/en/3592/explanations/db_authz.html
• API schema -> https://postgrest--3592.org.readthedocs.build/en/3592/explanations/schema_isolation.html
• Admin -> https://postgrest--3592.org.readthedocs.build/en/3592/references/admin_server.html
• Connection Pool -> https://postgrest--3592.org.readthedocs.build/en/3592/references/connection_pool.html
• ... (all major modules have a reference page)
• (except ApiRequest and Plan, here I think there would be no links, for now)

This would be great for end users, since you have all the PostgREST parts in one single diagram.

[laurenceisla]

Do you think there is any way to make the background transparent in both svgs instead of a sliiightly different color than readthedocs uses?

Yes, it is possible, will do that.

One thing though, should we have links in the arch diagram to the components or to the reference docs?

I had the same doubt, but I like that each component/interface is linked to its respective module in PostgREST source code. We could somehow do both if the components keep linking to the source code and the Notes on those components link to their docs counterpart. Also those that do not link to the source code (like API schema or Connection Pool) could link directly to the docs without needing Notes.

Not sure WDYT, maybe it could be untidy or confusing to do it that way?

[steve-chavez]

We could somehow do both if the components keep linking to the source code and the Notes on those components link to their docs counterpart

Sounds good to me, if the diagram maintains a nice layout with the added notes. That could be trouble, too much detail would make it less useful.

but I like that each component/interface is linked to its respective module in PostgREST source code.

I's less useful for end users that way, maybe more useful for us devs.. but only slightly so (the codemap below already contains the same info). The point of making the arch diagram part of the docs (instead of being a markdown file on the repo) was to make it more generally useful.

[steve-chavez]

but I like that each component/interface is linked to its respective module in PostgREST source code.

If we want to keep it that way, I'd say remove the architecture page from the docs and just move it back to a markdown file on the root of the repo. That way is clear that is for developers only.

[laurenceisla]

I's less useful for end users that way, maybe more useful for us devs.. but only slightly so (the codemap below already contains the same info)

Ahhh, yes, I see your point.

I'd say remove the architecture page from the docs and just move it back to a markdown file on the root of the repo

No, I think it's OK as you mentioned, with the links to the reference docs. It's a lot better for end users and devs can check below for the components.

[laurenceisla]

Done:

• Transparent background
• Links now reference the documentation counterpart of the component instead of the source code

(except ApiRequest and Plan, here I think there would be no links, for now)

I think Query also doesn't have a reference?

[steve-chavez]

Nitpick: the clickable area for the Authorization and API Schema links is only limited to the text, not the whole rectangle. Not a big deal if not possible.

On "Bird’s Eye View" we could also say that the boxes are clickable, otherwise it's easy to miss.

On "Schema Isolation", the "This page is a work in progress" note can be deleted.

[laurenceisla]

Nitpick: the clickable area for the Authorization and API Schema links is only limited to the text, not the whole rectangle. Not a big deal if not possible.

It seems to use the whole rectangle when it's small. I could not find an option that lets me do that for bigger rectangles.