mentorship-backend
mentorship-backend copied to clipboard
anitab-org
docs: issue530 backend visualisation
Description
This PR to add mentorship backend system visualisation diagrams to wiki.
Fixes #530
Type of Change:
- Documentation
How Has This Been Tested?
N/A
Checklist:
- [x] My PR follows the style guidelines of this project
- [x] I have performed a self-review of my own code or materials
@nandini45, I remember you said I could ask your help to review the diagrams. Will you still be able to help me with this? Thanks beforehand. Btw, the file I put in this PR (to go in wiki) has view only access. The file link I placed in the issue#530 description is with edit access so you can comment/modify the file if need to 😉.
@mtreacy002
- i had a question in the mentorship/backend-app diagram in database you didn't add the files of database that are db_utils and sqlalchemy_extension. although they are not connected to other files. still they are inter connected to each other. any reasons why?
- and i think app/api is enough instead of app/api-utils. 3.and one more thing we can have one image per page to be true reading the 2nd image is totally impossible. i cant read out anything in it. what does the second image consist of the code ? i know it might seems irrelevant to ask but i cant figure out.
- i had a question in the mentorship/backend-app diagram in database you didn't add the files of database that are db_utils and sqlalchemy_extension. although they are not connected to other files. still they are inter connected to each other. any reasons why?
Good catch, @nandini45. I might have missed them accidentally. I'll add them now 😉
- and i think app/api is enough instead of app/api-utils.
I was also wondering about that. I put -utils coz I thought app/api by itself can confuse people to think that those are the only files related to app/api, but it actually only things to do with utilities classes. What do you think?
3.and one more thing we can have one image per page to be true reading the 2nd image is totally impossible. i cant read out anything in it.
I agree, which is why at first I put the link to the file so people can zoom in and out for clarity. But you are right, probably I will add per section images underneath the second image for a better representation 😃 .
what does the second image consist of the code ? i know it might seems irrelevant to ask but i cant figure out.
The second image is similar to the class diagram where the top part somewhat shows attributes and the bottom part shows methods of the class. I emphasise here on similar to because it's not quite an exact technique to describe a class diagram 😂
Fix: System integration - with db_utils and sqlalchemy_extension.
Closer look to classes
Data persistence layer:
Data access layer:
Namespaces:
app/api - general
app/schedulers & utils
Service layer classes (app/api/resources):
user.py
admin.py
common.py
mentorship_relation.py
Hi @nandini45, I separated the classes by sections now. They look much clearer now (no zoom needed). It's just that I feel putting them in one page a bit too much. Maybe I should create different docs for different sections? Also, I didn't (haven't) put the testing classes there yet. But if they are placed in different docs (pages in wiki), then it'll beat the purpose of having a glance at them as a whole 😂 😂 (no different to going inside class one at a time in our IDE). Maybe we just skip the 2nd image altogether and just have the one image (1st image) as an overview of system integration. What do you think?
@mtreacy002 yeah i think so too. because i think users need not know so much details. they can just fork clone and check that much details in depth. the main image that is the first one seems good and provides a lot description about the py files used in backend.
Agree... So, should we keep it just with the first image and take out the class diagrams from the doc? Or keep it in there but on the same page not on different pages? I'm incline to just use the first image for overview and don't worry about using class diagrams for details 😂. @Isabel, can we also ask your opinion here?
yeah i wanted to say. ask isabel for further more opinion. for me i will say the 1st image provides a general overview which a user needs to know.
@SanketDG i agree that is way lot information for a beginner or any user i suppose. even maya would agree. we both were thinking to minimal it to only the main backend page. we are waiting Isabel opinion on it too.
@SanketDG, yes, as @nandini45 have said. If you looked at our previous comments you'll see that we're doubting placing the in depth class like diagrams which actually can be explored by the beginners themselves on their own IDE on the repo they've cloned. Thank you for adding your opinion here, anyway, we really appreciate it. We'll have to wait what @isabelcosta think of this (placing just 1st image as overview and skip the class diagrams). 😉
PS: I'm also a beginner and still learning, so, we're on the same boat 👍
Why this PR is not reviewed till now? I added Needs Review here, however I am not sure if it is On Hold or not
It was decided with @anitab-org/mentorship-maintainers that this PR will be closed in near future and a link will be added to the documentation for anyone who wants to look into this. As this visualization is not that beginner friendly