Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/pyrallux/cycle-count-app

React Frontend & Django Backend Full-Stack Nginx Web Application used to detect and fix inventory errors within ERP systems
https://github.com/pyrallux/cycle-count-app

axios bootstrap django django-cors-headers django-rest-framework docker docker-compose docker-secrets docker-volume-backup gunicorn js-cookie nginx react react-hook-form react-pdf-renderer react-query react-router-dom typescript vite yup

Last synced: about 1 month ago
JSON representation

React Frontend & Django Backend Full-Stack Nginx Web Application used to detect and fix inventory errors within ERP systems

Awesome Lists containing this project

README 

        
# Cycle Count App



## Structure



The app is a full-stack web application designed to be used within a `Docker` container. The entire application stack is made up of 4 parts: Frontend, Backend, WebServer, and Backup.



### Frontend



- The frontend is a `React` application built using the open-source javascript module bundler `Vite`.

- The majority of the frontend codebase is written in `typescript` and its dependencies can be found inside `./Frontend/package.json`.

- Frontend documentation on patterns used throughout can be found in `./Frontend/docs`. Additional documentation is present throughout various react `.tsx` files making up the bulk of the frontend.

- The Frontend relies on data from the backend to function properly. The url used to make calls to the database must be correctly configured in `./Frontend/src/api/apiConfig.ts`. Currently it is configured to query `https://cyclecount.app/db`.

- To run the application in development mode locally, run `npm run dev` inside `./Frontend`. A development version of the application be found at `localhost:5173`.

- In production, the frontend source files are not used, and code is compiled by running `npm run build` inside `./Frontend`. The compiled static application in `html` format can be found in`./Frontend/dist` when complete. This `dist` folder is placed within `./WebServer` in production to be served with `nginx`.



### Backend



- The backend is built upon the `Django` web framework using `djangorestframework` to handle requests; it is served using `Gunicorn` web server.

- The majority of the backend codebase is written in `python` and its dependencies can be found inside `./Backend/requirements.txt`.

- The backend writes all data to a `.sqlite3` database found in `./Backend/data`.

- Key files to the backend's functionality include:

  - `settings.py` managing high-level application settings as well as security header settings. Currently the application is configured to host the backend at  and only accept same-site requests from  over `https`.

  - `models.py` determining the various models used in the database, their fields, as well as any relationships between models.

    - NOTE: All changes made to models must be migrated to the database by running `django manage.py makemigrations` followed by `django manage.py migrate`, and each model and field must be properly reflected within `serializers.py`.

  - `urls.py` which determines the url patterns used by the django REST API framework.

  - `views.py` which links each url pattern with an underlying API call to a CRUD action in the database.

  - `admin.py` which manages which models should be present on the django administration site.

- In addition, a private key securing the backend must be provided in the root directory with the name `django-private-key.txt`.

- In development, the django server can be run locally by running `django manage.py runserver`. Running the server this way in production is bad practice.

- In production, the backend is served with `gunicorn`, and its the admin site's static `.css` files are served with `nginx`.



### Webserver



- The entire application is served to the web using `nginx`.

- Currently, nginx is configured to serve the site to  using `https`.

  - Both the `ssl` private key and public certification must be placed in the root directory named `ssl-private-key.txt` and `ssl-public-key.crt`.

- The nginx config can be found in `./WebServer/nginx.conf`.

- In production, as discussed earlier, the built frontend application should be placed in `./WebServer/dist`.



### Backup



- This aspect of the application is purely used to backup the `.sqlite3` database bi-weekly. It uses a third-party `Docker` image to backup the database volume within the container.

- Backups are saved to `./Backup/archive` and configuration files for various settings such as the time, frequency, and format of backups can be found in `./Backup/backup.env`. Backups are currently configured to be pruned after 60 days.

- Information on how to use these backups to restore the database can be found in `./Backup/db-restore.md`.



## Docker Container Info



- The application has been developed to be used inside of a docker container. `Docker-Compose` allows the app to nicely break the application down into 3 interdependant services: WebServer, Backend, and Backup.

- Each service generates its own image or virtual linux environment that is complete with its own requirements. This top-level configuration can be found in `./compose.yaml`. Additionally, each service has its own `dockerfile` outlining the commands needed to properly install requirements and start the service within the virtual container.

- `Volumes` are used within the application to link data within the virtual containers with the local filesystem. Plus, Docker `secrets` allow private keys to be used by containers without them needing to be present within the potentially vulnerable virtual image.



## Running the Application



1. Clone this repository.

2. Build the frontend with `npm run build` and place the generated `dist` folder inside the `./WebServer` folder.

3. Place the proper secret `django-private-key.txt`, `ssl-private-key.txt`, and `ssl-public-key.txt` files in the root of the directory.

4. Run `docker compose up -d` in the home directory to build the docker container (Prior docker installation is required).

5. Access the app through a browser at  (Authentication is required for access).