Developer Scripts

Relevant source files

The following files were used as context for generating this wiki page:

• scripts/generate-keys.ts
• scripts/seed.ts
• package.json
• deploys/deploy.sh
• SETUP.md
• deploys/README.md

The project utilizes a collection of scripts to automate and standardize common development, testing, and deployment tasks. These scripts are a mix of pnpm commands defined in package.json, TypeScript files executed with tsx, and shell scripts for deployment operations. They are essential for setting up the development environment, managing the database, running services, and deploying applications.

The primary entry points for these automations are the scripts defined in package.json. These scripts orchestrate more complex operations by calling Node.js/TypeScript files or shell scripts, ensuring a consistent workflow for all developers. Key initial setup tasks, such as key generation and database migration, are handled by these scripts and are mandatory before running the application.

Sources: package.json, SETUP.md:19-38

Script Overview

The project's scripts are defined in the scripts section of package.json and can be invoked using pnpm run <script_name>. They are categorized by function: development, database management, testing, and utilities.

The following diagram illustrates the relationship between pnpm commands and the underlying script files.

Key package.json Scripts

This table summarizes the most important scripts available to developers.

Script Name	Command	Description
dev:all	concurrently "nest start --watch ..."	Starts all microservices and the gateway in development watch mode.
build:all	nest build --all	Builds all applications in the monorepo for production.
test	jest --config ./jest.unit.js	Runs all unit tests across the project.
test:full	pnpm test:compose:up && ...	Executes the full end-to-end test suite, including setting up test containers.
db:gen:all	prisma generate --schema=...	Generates Prisma clients for all microservices.
db:migrate:all	prisma migrate dev --schema=...	Runs database migrations for all services. This is a critical setup step.
db:reset:all	prisma migrate reset --schema=...	Resets all databases to their initial state.
generate:keys	tsx scripts/generate-keys.ts	Generates the RSA public/private key pair required for JWT authentication.
seed	tsx scripts/seed.ts	Populates the databases with initial seed data (users, products, etc.).

Sources: package.json:5-48, SETUP.md:34-38

Utility Scripts

These are standalone TypeScript scripts located in the scripts/ directory, executed via pnpm commands.

Key Generation (generate:keys)

This script is responsible for creating the asymmetric RSA key pair used for signing and verifying JWTs. The user-app uses the private key to sign tokens, and all other services (including the gateway) use the public key to verify them. This is a mandatory step during initial project setup.

The script performs the following actions:

1. Checks if the keys/ directory exists at the project root. If not, it creates it.
2. Generates a 2048-bit RSA key pair using the RS256 algorithm.
3. Saves the keys in PEM format as private-key.pem and public-key.pem inside the keys/ directory.

Sources: scripts/generate-keys.ts, SETUP.md:25-27, package.json:42

The key generation process is visualized in the flowchart below.

Database Seeding (seed)

The seed script populates the various application databases with initial data. This is useful for setting up a development or testing environment with a consistent dataset.

The script connects to the database using the Prisma client and executes a series of data creation functions:

1. Creates a default admin user and several regular users.
2. Creates a hierarchy of product categories.
3. Creates a set of products, associating them with the previously created categories and users.

Sources: scripts/seed.ts, package.json:48

The following sequence diagram shows the interaction between the seed script and the database.

Deployment Script

The project includes a shell script for deploying individual microservices to a host environment.

deploys/deploy.sh

This script simplifies the deployment of a single microservice container. It is designed to be run on the target host machine from within the deploys/ directory.

The script's workflow is as follows:

1. Input Validation: Checks if an application name (e.g., user-app, gateway) was provided as an argument.
2. File Check: Verifies that the corresponding [app-name].yml Docker Compose file and the .env configuration file exist.
3. Environment Loading: Loads environment variables from the .env file.
4. Image Pull: Pulls the specified version of the Docker image from the configured Docker registry.
5. Container Restart: Stops any existing container for the application and starts a new one in detached mode using docker compose.
6. Status Check & Logging: Confirms the container is running and tails the logs.

Sources: deploys/deploy.sh, deploys/README.md:105-122

The deployment flow is shown below.