Software Design
This page includes a short description of the overall architecture style of the system, its high-level system components, and their logical (what data they exchange) and control (how they invoke each other) dependencies. Mostly described using diagrams.
Architecture Diagram
A NextJS-Django stack built on Docker and hosted on Cybera. The frontend will be statically built, the django server will be running on a separate container. The server will be running the business and persistence layers. The DB is postgres and will be a docker volume attached to the Django container. In addition emails will be sent through Sendgrid. The frontend will communicate with the backend using REST in JSON (header + body) format.
UML Class Diagram
This is an ER diagram of the app. There are two main types of accounts, Admin and User. User can follow 0 or many companies. They also have attributes attached to the user and can be extended upon like a mentor. Users can also have badges. Admin manages users, activities and scholarships.
Sequence Diagrams
Multiple sequence diagrams depicting the most important scenarios. There is a diagram for each major user: Students, Organizations, Mentors and Admin.
Figma Prototype User interface
API Documentation
API documentation is available at http://api.platform.pathfinder.test/docs/ / http://[2605:fd00:4:1001:f816:3eff:fe17:6af6]:8000/docs/
Requirement Traceability Matrix
| Requirement Description | Related US | Test Case File Location | Test Result |
|---|---|---|---|
| Fetch Resources | U.S. 6.01 | resources/tests.py | Pass |
| Filter Resources | U.S. 6.02 | tests/resources.test.jsx | Pass |
| Edit Profile | U.S. 1.02 | cypress/e2e/editProfile.cy.js | Pass |
| Badge System | U.S. 4.01 | app/test_badges.py | Pass |
| Display Badge | U.S. 4.02 | tests/badges.test.jsx | Pass |
| Fetch Opportunity | U.S. 2.02 | opportunity/tests.py | Pass |
| Explore Opportunity | U.S. 2.02 | tests/job-view-page.test.jsx | Pass |
| Opportunity Details | U.S. 2.02 | tests/oportunityDetail.test.jsx | Pass |
| Fetch Project-based learning | U.S. 5.02 | activities/tests.py | Pass |
| Fetch Scholarship | U.S. 5.01/5.02 | scholarships/tests.py | Pass |
| Fetch Mentors | U.S. 3.01 | mentor/tests.py | Pass |
| Explore Mentors | U.S. 3.01 | tests/mentorList.test.jsx | Pass |
| View Calendar | U.S. 2.05/2.06 | tests/calendar.test.jsx | Pass |
| Login | U.S. 1.01 | tests/login.test.jsx | Pass |
| Register | U.S. 1.01 | tests/register.test.jsx | Pass |
| View Project-based learning | U.S. 5.02 | tests/activity-view-page.test.jsx | Pass |
UI Design Principles
- Visibility of System Status: When user clicks on the filtering buttons/searching with keywords, the website presents the corresponding feedback to the user immediately; when user goes to different page, the details and information of that page is displayed immediately
- Match Between the System and the Real World: the wordings and icons used in the website all match the real-world conventions and self explanatory. For example, the icon for the Opportunities tab is a briefcase icon
- User Control and Freedom: There are go back buttons across all the pages. For example, if the user misclicked on applying a job, they can click on the back button and go back to the job description instead of forcing them to apply the job. There is also a navigation bar appears on every page that users can use to navigate back to a certain page. Users can edit their profile if they entered something incorrectly and cancel job application if they applied accientally
- Consistency and Standards: The layout for each page is consistent, a navigation bar is displayed across the website. Each page usually comes with a search bar at the top of the screen, main information section in the middle and filtering options on the right. The wording is also consistent. We use plural terms for items that can have multiple instances, and when clicking on a single item, we use the singular form
- Error Prevention: We prevent users from submitting the form if they didn't fill in the mandatory fields. For example, if the user is trying to apply a job without filling any application detail, and error message will tell the user that application detail cannot be empty
- Recognition Rather than Recall: Users can always refer to the profile page to see the information they filled in and the username of the login user is displayed all the time. The navigation bar allows users to go to different pages without memorizing the steps to do so. The available filtering options are also displayed
- Flexibility and Efficiency of Use: Provided navigation bar for users to quickly access certain page, or they can simply click on go back buttons to go back to the last page they was on
- Aesthetic and Minimalist Design: The current interfaces are clean, everything displayed on each page is relevant and needed. For example, it only displays resources and their corresponding filtering options on the resources page
- Help Users Recognize, Diagnose, and Recover from Errors: All the error messages are expressed in plain language with no error codes and indicate the problem and solution. For example, if the user forgot to fill in certain field on the profile edit page, it will show an error "Please fill in the mandatory field" and highlights the missed field
- Help and Documentation: In our login/profile/job application pages, we have hints text displayed on each input field telling the users what is expected in each form
Accessibility
- Existing colors on our website: black text, white & yellow background, blue & red buttons, blue, green and yellow tags
- Colors pass contrast check(passed most tests): Black and White: 16.9, Yellow and Blue: 5.36:1, White and Blue: 5.14:1, Black and Green: 12.05:1, Black and Yellow: 13.71:1, Blue and Black: 11.65:1, Red and White: 5.03:1
- Clear layout: each page have distinct sections which make it easy to locate informtion
- Search bar & filters: able to find information efficiently
- Navigation bar: easy to access different pages
- Calendar: easy to view all the job, scholarship and activities in one place
SonarCube Results - Static Code Analysis
SonarQube is a code quality analysis tool that analyzes the source code and provides a report of the project. It analyzed Security, Reliability, Maintainability, Accepted Issues, Test Coverage, Code Duplications and Security Hotspots
- Security: E because we kept the Django secret key inside settings.py for future maintaince
- Reliability: E because we are building on top a brownfield project, so some of the code that we reused have some existing issues, mainly are issues like certain props are missing in props validation
- Maintainability: A because there is no major maintainability issue and even though there are 2.6k open issues, they are something minor such as "remove this commented out code" and "remove the unused local variable"
- Accepted Issues: 0 because we did not use SonarLint
- Coverage: 0% test coverage because we used different kind of test tools like Django Test and Jest, and it did not capture our tests properly
- Duplications: 11.6% duplicated lines across 55k lines of code so not really a big issue
- Security Hotspots: E because it detected we hardcoded "password", but the password is only used for the tests
Job Description
Job Description is available on Git Repo.
User Manual
User Manual is available on Git Repo.
Deployment Instruction
Deployment Instruction is available on Git Repo.
Technology List
Backend
Django
High level Python web framework: https://www.djangoproject.com/
django rest framework
Toolkit for building Web APIs in django. Also provides api test functionality.: https://www.django-rest-framework.org/
djoser
Provides a set of Django Rest Framework views to handle basic authentication actions: https://pypi.org/project/djoser/
Sendgrid
Email delivery platform: https://sendgrid.com/
Swagger
Provides tools for API documentation: https://swagger.io/
Database
SQLite
Lightweight database that is suitable for development: https://www.sqlite.org/index.html
PostgreSQL
Powerful, open source object-relational database system, suitable for production: https://www.postgresql.org/
Frontend
Tailwind
Tailwind is a class based css framework: https://tailwindcss.com/
Jest
Jest is a testing framework for the frontend: https://jestjs.io/
Cypress
Cypress is an e2e testing framework: https://www.cypress.io/
NextJS
A react framework meant to be SSR but has options for static builds: https://nextjs.org/
Deployment
Cybera
Not-for-profit corporation responsible for the operation of Alberta's Optical Regional Advanced Network: https://www.cybera.ca/
DevOps
Docker
Docker is an container application to isolate and deploy applications: https://www.docker.com/
Docker compose
Extends Docker for running multi-container applications: https://docs.docker.com/compose/
traefik
Manages container networks: https://traefik.io/