[DOC] - Create architecture diagram

[kcpevey]

Preliminary Checks

• This issue is not a question, feature request, RFC, or anything other than a bug report. Please post those things in GitHub Discussions: https://github.com/nebari-dev/nebari/discussions

Summary

Need to create architecture diagram(s) for jhub-apps.

Steps to Resolve this Issue

NA

[viniciusdc]

I made a simple draft so far just to self-situate, I will most probably split this into 2 separate diagrams, one for the overall capabilities of the service, and one regarding networking (auth, services, redirections)

[viniciusdc]

[viniciusdc]

New version

[viniciusdc]

@aktech @kcpevey what do you think?

[dharhas]

Should we include a section around getting roles and permissions from keycloak/jhub5?

[tylergraff]

I'd like to see additional detail added to give developers (with minimal knowledge of the system) insight into where in the repos to look for details and implementations of the pieces shown in this diagram, including:

• What an "app" is, where/how they are defined, and where they are stored
• What a "single user notebook server" is and where it is defined
• What "Pages" are and where/how they're defined
• What constitutes the "service" interface (edge) between jupyterhub and Jhub Apps, and where that interface is defined
• What component maintains "Conda Environments" and how they are accessed by Spawners and Apps

The 'where/how defined' details could simply be corresponding class names and repos+filepaths

[kcpevey]

I'd like to see additional detail added to give developers (with minimal knowledge of the system) insight into where in the repos to look for details and implementations of the pieces shown in this diagram, including:

• What an "app" is, where/how they are defined, and where they are stored
• What a "single user notebook server" is and where it is defined
• What "Pages" are and where/how they're defined
• What constitutes the "service" interface (edge) between jupyterhub and Jhub Apps, and where that interface is defined
• What component maintains "Conda Environments" and how they are accessed by Spawners and Apps

The 'where/how defined' details could simply be corresponding class names and repos+filepaths

@tylergraff are you thinking of something like a glossary that would sit beside this diagram?

[tylergraff]

are you thinking of something like a glossary that would sit beside this diagram?

@kcpevey yes I think that would work. Or the diagram could be expanded to fit descriptions in text boxes near relevant diagram features.

[viniciusdc]

@tylergraff @kcpevey Regarding the descriptions/details, I assumed we would have some docs for those components; that's why I avoided adding too many labels in the diagram itself. If folks like the overall direction of the latest iteration above, I could open a PR, adding an extra infrastructure docs page going into more details.

@dharhas @kcpevey Regarding the permission model, I think this might be better explained in its own doc page

[kcpevey]

@viniciusdc that all sounds good to me. I think once we see this diagram and the text around it to give it context, we'll have more clarity.

Go ahead and open a PR and we review with full context.

And do be clear - I agree the permissions model is likely to need a whole dedicated page (or subsection of this page). I think we should exclude that here since that's currently in the process of changing, but we'll definitely need to include it after the permissions revamp is done.

[viniciusdc]

Sure thing, I will be opening this today