Server

The server directory contains backend JavaScript (NodeJS/Express) codes for running and managing ACAP's REST APIs.

ACAP promotes using REST APIs running on the backend to securely perform mutative "WRITE" operations in the Firestore database to allow the creation of more robust server-side input validation scripts for simple to complex input data than relying alone on limited Firestore Rules (opens in a new tab) for access checks and data validation.

Maintaining a separate backend for securely performing database WRITE operations also syncs with ACAP's requirements to host its frontend UI in GitHub Pages while having access to a secure, remote backend protected by established Security guidelines and adhering to best practices in enforcing web security to maintain sensitive data protection and integrity.

⚠️

While using the Firestore WEB APIs (opens in a new tab) "directly" in the UI instead of going through the Node backend is also an alternate option, developers should be aware of possible security attack vectors that could open up and how to counter them by having a thorough understanding of how the Firebase Authentication (opens in a new tab), Firebase Custom Claims (opens in a new tab) and Firestore Rules (opens in a new tab) work in sync to keep sensitive user information safe and secure.

💡

One of the key things to note here is that using the serverless Firestore WEB APIs (opens in a new tab) to manage data "directly" in the Firestore database through the frontend UI with client-side validation logic, where we install its JavaScript APIs, also enables the Firestore REST APIs (opens in a new tab) along with it, which is accessible on other clients, such as a browser console, or Postman, outside the "safety" confines of the frontend UI.

Knowing that there are two (2) points of data entry to anticipate and the nature of input data should enable developers to make informed decisions about when to use the Firestore WEB APIs (opens in a new tab) (preferably with fool-proof Firestore Rules (opens in a new tab)) directly or if they need to delegate operations in a more secure environment, such as the Node backend server.

Files

.env - Dotenv: NodeJS library that loads configuration files from a .env file
.env.example - example keys and values to put in the server .env file
Dockerfile.acap - multi-stage build Dockerfile definition for running the server on localhost development with livereload using the nodemon library, or built to run for production deployment without livereload
Dockerfile - Used for running the server production deployment on Render
package.json / package-lock.json - Contains definitions of the server's NodeJS dependency libraries
/src/index.js - server program entry point

Folders

/api

Contains the index.js file that converts the stand-alone Express app into a single serverless function format recognized by Vercel.
This option only becomes available if deployment to Vercel is activated.

Express server (Folder)

/middleware

contains scripts that handles Cross-Origin Requests (CORS), router-level data validation and user authentication

/controllers/index.js

contains routing scripts that associates URLs with controller actions

/controllers

contains scripts that handles requests, mapping them to target models (classes) and returns success or error responses
These sripts, along with the /middleware and /models make up the REST APIs.

/models (classes)

provides methods, organized into categories (classes) for interacting with the database

/scripts (Folder)

The scripts directory contains a large collection of Node Package Manager (NPM) scripts used for data processing, uploading and cleanup functions. More information about these scripts are available in the /server/README.md file's Available Scripts - server section.

/scripts/cron

contains NPM scripts that run as cron jobs in GitHub Actions Scheduled Workflows

/scripts/data

contains sample data files in JSON, CSV and EXCEL formats for reference on established data structures and formatting

/scripts/seeders

contains NPM scripts for initializing the Firestore database with default data

/scripts/uploaders

contains NPM scripts for facilitating raw data file uploads to the Firestore database

/scripts/generate-docs

contains scripts for generating ACAP's REST API documentation

/scripts/tools

contains functions for archiving and deleting old PAGASA weather forecast data

/utils (Folder)

contains various utility helper functions i.e., for date, processing strings, and others

/utils/pdf

contains scripts that manages the bulletin PDF layouts for seasonal, 10-day and special bulletins

File Tree

This tree shows only the relevant server files and directories.

- index.js
.env
.env.example
.dockerignore
Dockerfile
Dockerfile.acap
package-lock.json
package.json

Client Deployment