Developer Scripts

Relevant source files

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

• services/api/package.json
• services/web/package.json
• services/web/scripts/generate-version.js
• scripts/deploy.sh
• deployment_guide.md
• README.md

The email-platform repository includes a collection of scripts to automate common development, build, configuration, and deployment tasks. These scripts, written in Bash, Node.js, and TypeScript, are crucial for maintaining a consistent development environment and streamlining the process of deploying the application to production.

The scripts cover several key areas: running local development servers, building production assets, managing database schemas, setting up environment configurations, and automating production deployments. They are primarily executed via NPM scripts defined in the package.json files for the api and web services.

NPM Scripts

The project uses NPM as a task runner. Key scripts are defined in the package.json files of the api and web services, providing a unified interface for developers.

Sources: services/api/package.json:5-15, services/web/package.json:5-12

Script	Service	Description
dev	api	Starts the API server in development mode with hot-reloading using tsx.
dev	web	Runs generate-version.js then starts the Vite development server for the frontend.
build	api	Compiles the TypeScript source code into JavaScript in the dist/ directory using tsc.
build	web	Runs generate-version.js, compiles TypeScript, and builds the frontend assets for production using Vite.
start	api	Starts the compiled API server from the dist/ directory.
prisma:migrate	api	Runs Prisma database migrations for development.
prisma:deploy	api	Applies pending Prisma migrations to a production database.
test	api, web	Executes the test suite using Vitest.
create-admin	api	Executes the scripts/create-admin.ts script to create an administrator user.

Example package.json Scripts Section

This snippet from the API service shows how scripts are defined.

// services/api/package.json:5-15
  "scripts": {
    "dev": "tsx watch src/index.ts",
    "build": "tsc",
    "start": "node dist/index.js",
    "prisma:generate": "prisma generate",
    "prisma:migrate": "prisma migrate dev",
    "prisma:deploy": "prisma migrate deploy",
    "lint": "tsc --noEmit",
    "test": "vitest run",
    "test:watch": "vitest",
    "create-admin": "tsx scripts/create-admin.ts"
  },

Sources: services/api/package.json:5-15

Environment & Configuration

Environment File Generation (generate_env.sh)

The project includes a shell script, scripts/generate_env.sh, to bootstrap the necessary .env files for a production environment. This ensures that all required environment variables are present before deployment.

The script creates .env files within the services/api/ and services/web/ directories. It is designed to be run from the project root.

The following diagram illustrates the workflow of the generate_env.sh script.

This diagram shows the process of generating environment configuration files for the API and Web services.
Sources: deployment_guide.md:41-48

Build & Versioning

Frontend Version Generation (generate-version.js)

The web service uses a Node.js script to embed build-time information into the frontend application. This script is automatically executed during the dev and build processes.

File: services/web/scripts/generate-version.js

The script performs the following actions:

1. Ensures the services/web/public directory exists.
2. Creates a version.json file inside the public directory.
3. Populates the file with the current timestamp as the version and the build time in ISO format.

This allows the frontend to fetch version.json for cache-busting or displaying build information.

// services/web/scripts/generate-version.js:14-17
const versionData = {
    version: Date.now().toString(),
    buildTime: new Date().toISOString()
};

Sources: services/web/scripts/generate-version.js, services/web/package.json:6-7

Data Management

Admin User Creation (create-admin.ts)

A TypeScript script, services/api/scripts/create-admin.ts, is provided to provision an initial administrator account. This is essential for the first-time setup of the application. The script is executed via the npm run create-admin command in the api service.

The script connects to the database via Prisma and creates a new user with the ADMIN role, using credentials typically sourced from environment variables.

The sequence diagram below shows the interaction for creating an admin user.

This diagram illustrates the process of a developer running the create-admin script to add an admin user to the database.
Sources: services/api/package.json:14, README.md:32-35

Deployment & Operations

Production Deployment (deploy.sh)

The scripts/deploy.sh script automates the deployment process to a production environment. It is designed to be run on the production server and ensures a zero-downtime update where possible.

The script follows these steps:

1. Pulls the latest code from the main branch of the git repository.
2. Rebuilds and restarts all services using docker-compose.prod.yml.
3. Waits for 10 seconds to allow services to stabilize.
4. Executes database migrations using prisma migrate deploy inside the api container.
5. Restarts the api service to ensure it picks up any schema changes from the migration.

# scripts/deploy.sh:10-26
# 1. Pull latest code
echo "📥 Pulling latest code from git..."
git pull origin main

# 2. Rebuild and restart containers
echo "mb Rebuilding and restarting containers..."
# Use docker-compose.prod.yml explicitly
docker compose -f docker-compose.prod.yml up -d --build

# 3. Wait for database to be ready
echo "⏳ Waiting for services to stabilize (10s)..."
sleep 10

# 4. Run Database Migrations
echo "📦 Running database migrations..."
if docker compose -f docker-compose.prod.yml exec api npx prisma migrate deploy; then
    echo "✅ Migrations applied successfully."
else
    echo "❌ Migration failed. Attempting to resolve potential conflicts..."
    # Optional: logic to handle specific migration errors if needed
    exit 1
fi

# 5. Restart API to ensure it picks up new schema/config
echo "🔄 Restarting API service..."
docker compose -f docker-compose.prod.yml restart api

Sources: scripts/deploy.sh, deployment_guide.md:149-158

The following flowchart visualizes the deployment process.

This diagram shows the automated steps executed by the deploy.sh script for a production update.
Sources: scripts/deploy.sh, deployment_guide.md:149-158

Database Backup (backup.sh)

The project provides a scripts/backup.sh script for creating automated backups of the PostgreSQL database. While the script file is not in the context, its functionality is detailed in the deployment guide.

Key features include:

• Manual & Automated Execution: Can be run manually or via a cron job.
• Cron Job Setup: The guide recommends a cron job to run the backup every 6 hours.
• S3 Upload (Optional): Supports uploading the backup file to an S3 bucket.
• Restore Process: The guide provides a command to restore the database from a backup file using docker-compose exec.

Sources: deployment_guide.md:112-146

Conclusion

The developer scripts within the email-platform repository are essential tools that enforce consistency and automate repetitive tasks. They cover the full development lifecycle, from initial environment setup with generate_env.sh, through daily development with npm run dev, to production deployment and maintenance with deploy.sh and backup.sh. By using these scripts, developers can ensure a smoother, more reliable, and efficient workflow.