pgadn-website-project-onboarding

pgadn-website-project-onboarding.md

PGADN Website Project Onboarding

This documentation aims to provide a general overview of the website project and directory design pattern for the official website of the Province of Agusan del Norte (PGADN).

In this document, we will explore the configuration and setup that is currently being used for the project.

Further, we will explore the 2 main folders that our project extensively use, namely:backend and frontend folders. These folders reside within the root folder and within each main folder there exists a standard directory design pattern for which each contributing developer must follow.

Imposition of the configuration and design pattern throughout the project must be strictly observed at all times in order to avoid confusion and allow all developers to maintain familiarity of purpose of all files and folders.

Backend x Frontend

Let us breakdown how our PGADN website project is currently setup in terms of backend and frontend development.

The project is setup to run all client-side related operations using React for UI/UX purposes, and webpack for bundling purposes. All related files exist in /frontend/ folder of our project.

All dynamic contents inside our React application are dependent on our web API. For this purpose, we are using Django only for serving our web API, and the static and media files. All related files are located in /backend/ folder of our project.

Here are the lists of tools for this project:

• Tools required in all machines

  • git (version control)
  • python
  • npm (package manager)
  • postgresql

• Development Tools

  • vscode (editor, recommended)
  • dbeaver (db software, recommended)
  • source tree (git GUI software, recommended)

• Frontend Tools

  • react
  • webpack
  • babel
  • eslint
  • prettier
  • redux

• Backend Tools

  • django
  • django-rest-knox (authentication using knox)
  • django-rest-framework (drf) (for RESTful API)
  • django-cors-headers (for CORS implementation)

• Production Server Tools

  • freebsd (server OS)
  • nginx (overall web server)
  • uwsgi (for serving Django codebase)

Main Modules

Before we start, it is important for us to know what modules the project is expected to have.

The PGADN website has 3 main modules, namely: web_app, jobnet_app, employee_app, and account_app

The web_app module is responsible for rendering UI and information for public consumption. In this module, we have sub-modules such as news, document, vacancies, etc.

jobnet_app module, on the other hand, is responsible for catering the online job application services of the province. Sub-modules include pds among others.

employee_app module is used for internal purposes. This module shall allow the Capitol employees to post news/blog contents or upload transparency documents, perform admin operations, manage leave applications, etc.

Finally, account_app module contains the codebase for managing users and handling authentication. This contains sub-modules such as login, signup, password reset, etc.

1. frontend

The frontend folder shall be seen immediately inside the root folder. In this folder, all files and folders related to frontend configuration and React implementations must reside.

In the current setup, the frontend folder shall contain 3 folders and 8 files with the following purpose:

Folders

1. dist-build

   Everytime we rebuild the frontend module for preparation to deployment, all build files shall be located within the dist-build folder.

   Within, there exists static folder with sub-folders for holding the respective assets: css and js (as defined in our webpack configuration).

   Once these files are generated, we must copy+paste them (with the same, respective folder name) to our static folders in Django in order for these files to be served properly. The copy+pasting procedure is automatically performed and is part of our npm run build command (as defined inside package.json file under scripts config).

   Also in static, there is index.htmlfile. During deployment, in our production server, we must point our server to this file as the website's index or main entry point.

   Except for index.html, all other files and folders inside the dist-build folder shall be untracked via the .gitignore file.

   There is no point for us to track this in git as files will be copied in Django's static. The static-related folders in Django are the one's that will be tracked by git.

   During rebuild, index.html may have updates so we need to keep tracking of this file. This is the reason why this is excluded from .gitignore.

2. node_modules

   If you are familiar with npm, this is pretty straightforward.

   This folder serves as the installation path for all npm libraries we have locally-installed in this project.

3. src

   If you are familiar with the React environment, src shall be recognizable as well. This folder comes by default but can be renamed if need be.

   Since the React module was created via the create-react-app command, the name src becomes part of React's default configuration and thus been provided.

   Renaming this folder directly without performing proper configuration is expected to break the entire project. Hence, if a rename is required, it shall be constituted by all developers involved, or by the technical managing team.

   The src folder has inner files and folders in its root, with the following purpose:

   1. index.html

      Serves as the main entry point of the project UI, in development mode.

      The <div id="react-root"></div> element is where React scripts will be injected for rendering.

   2. index.js

      Serves as main React file where all components shall be consolidated.

      As configured, scripts will be rendered client-side by injecting the scripts inside an element with attribute id="react-root".

   3. Route.js

      Defines which module must be called and rendered based on route that is currently being called.

      For example, if entire URL path contains a main path of /jobnet/, it will render the Jobnet module and all respective components.

   4. serviceWorker.js

      This file comes by default when the frontend module was first created via the create-react-app command.

      This file is used for implementing Progressive Web App (PWA). Although the current version of this project isn't currently implementing PWA, the file was not deleted as this can be used as reference later.

   5. global

      The global folder currently has 3 sub-folders: data, function, and ui.

      It is a global folder for holding components and other js files that are universal to the entire frontend module.

      For example, we want to use a loading component with the same behavior and styling in all of our main modules. Instead of coding a component in each module for the same purpose, it would be better to just code the component once, then reuse them where need be.

      The loading component shall then be defined within global/ui folder. For example, /global/ui/LoadingUI.js. The ui sub-folder holds all UI-related components, or a component that renders an interface.

      The data sub-folder holds all global data declarations that are static in nature. For example, we have different form components across our app with a civil status dropdown field with the same options. Instead of hard-coding a variable in each of these components, we can just declare it once in the data folder and reuse them where need be.

      If we have non-UI functions that we need to make reusable in the entire app, we place them inside the function sub-folder. For example, we need a function to capitalize a string. Instead of defining such function in the file where we need it, we can just define the function once and reuse it in the component where we need it.

   6. [name]_app

      Folder with name pattern of [name]_app indicates that it is a module folder.

      In React environment, we can divide our whole app in segments of modules to separate our codebase respectively.