Local Development Setup

Relevant source files

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

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

The email-platform project is a multi-service application consisting of a backend API, a frontend web application, and several backing services. Setting up a local development environment can be done using Docker Compose, which is the recommended approach for a quick start, or by running each service manually. This document outlines both methods.

The Docker-based setup provides a complete, containerized environment that mirrors the production setup, including the API, web client, database, cache, and an email testing tool. The manual setup offers more granular control over individual services, which can be useful for focused development on either the frontend or backend.

Architecture Overview

The local development environment, when run with Docker Compose, consists of several interconnected services. The web service (frontend) communicates with the api service (backend), which in turn relies on Postgres for data persistence and Redis for queuing and caching. For email testing, an SMTP server is provided by the api service, and emails can be viewed through the Mailpit web interface.

Sources: deployment_guide.md:65-72, README.md:21-29

This diagram illustrates the services launched by the local development docker-compose.yml.

Setup Methods

There are two primary ways to set up the local environment: using Docker (recommended) or running services manually.

1. Docker-based Setup (Recommended)

This is the quickest way to get all services running. It uses docker-compose to build and run all the necessary containers.

Steps:

1. Configure Environment: Copy the example environment file for the API.

   cd services/api
   copy .env.example .env
   

   You can update secrets like JWT_SECRET if needed.
   Sources: README.md:31-35

2. Build and Run Containers: From the project root directory, run:

   docker compose up --build
   

   This command will start all the services defined in docker-compose.yml.
   Sources: README.md:38-40, deployment_guide.md:64-65

3. Apply Database Migrations: Once the containers are running, apply the database schema.

   docker compose exec api npx prisma migrate deploy
   

   Sources: README.md:42-44

The following services will be available:

Service	URL	Description
API	http://localhost:3001	The backend RESTful API.
Web	http://localhost:5173	The frontend React application.
SMTP Inbound	localhost:2525	The SMTP port to send test emails to.
Mailpit	http://localhost:8025	A web UI to view emails sent to the local SMTP server.
Postgres	localhost:5432	The PostgreSQL database.
Redis	localhost:6379	The Redis instance for caching and queues.

Sources: deployment_guide.md:67-72, README.md:33-36

2. Manual (Non-Docker) Setup

This method involves running the API and web services directly on your host machine. You will need to have Node.js and a PostgreSQL database instance running separately.

API Setup:

1. Navigate to the API directory: cd services/api
2. Copy the environment file and configure DATABASE_URL to point to your local Postgres instance: copy .env.example .env
3. Install dependencies: npm install
4. Generate Prisma client: npm run prisma:generate
5. Run database migrations: npx prisma migrate dev --name init
6. Start the development server: npm run dev

Sources: README.md:100-107

Web Setup:

1. Navigate to the web directory: cd services/web
2. Copy the environment file and set VITE_API_BASE if your API is not running on http://localhost:3001: copy .env.example .env
3. Install dependencies: npm install
4. Start the development server: npm run dev

The web application will be available at http://localhost:5173.

Sources: README.md:52-57

Key Scripts

The package.json files for both the API and web services define several scripts for common development tasks.

API (services/api/package.json)

Script	Description
dev	Starts the API in watch mode using tsx.
build	Compiles the TypeScript code to JavaScript.
start	Runs the compiled JavaScript code.
prisma:migrate	Creates and applies a new database migration in development.
prisma:deploy	Applies existing migrations to the database.
test	Runs the test suite using vitest.
create-admin	A script to create an administrative user.

Sources: services/api/package.json:6-16

Web (services/web/package.json)

Script	Description
dev	Runs a script to generate version.json and starts the Vite dev server.
build	Generates version.json, runs the TypeScript compiler, and builds the app for production with Vite.
lint	Lints the codebase with ESLint.
test	Runs the test suite once with vitest.
test:watch	Runs vitest in watch mode.

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

Testing

The project includes unit and integration tests for the API, and component tests for the web application.

Running Tests

• API Tests:

  # From services/api directory
  npm test
  

• Web Tests:

  # From services/web directory
  npm test
  

A test database is required for API integration tests. The testing plan suggests running a separate PostgreSQL container on a different port (e.g., 5433) for this purpose.

Sources: TESTING_PLAN.md:21-27, services/api/package.json:13, services/web/package.json:9

Sending a Test Email

With the Docker environment running, you can send a test email to the local SMTP server. The README.md provides a Python script for this purpose.

This sequence diagram shows the flow of sending and viewing a test email.

First-time Login

After starting the services and applying migrations, the system seeds a default admin user.

• Email: admin@example.com (from DEFAULT_ADMIN_EMAIL env var)
• Password: changeme (from DEFAULT_ADMIN_PASSWORD env var)

You can log in using the web UI or by making a POST request to the /auth/login endpoint.

Sources: README.md:46-50