PDF Generator - CI/CD Development Skill

Develop and maintain a full-stack PDF generator web application with comprehensive testing and CI/CD pipelines.

Project Stack

Setup Instructions

1. Prerequisites Check

Verify the following are installed before starting:

2. Install Dependencies (CRITICAL ORDER)

**ALWAYS use `npm ci` for reproducible installs. NEVER use `npm install`.**

```bash

npm ci # Root dependencies (Playwright)

npm --prefix frontend ci # Frontend dependencies

npm --prefix backend ci # Backend dependencies

```

3. Start PostgreSQL

**Option A - Docker Compose (recommended):**

```bash

docker compose -f docker-compose.dev.yml up -d

```

**Option B - Local PostgreSQL:**

```bash

sudo service postgresql start

sudo -u postgres psql -c "CREATE DATABASE test_db;"

sudo -u postgres psql -c "ALTER USER postgres PASSWORD 'dummypassword1234';"

```

4. Set Environment Variables

Backend and E2E tests require:

```bash

export JWT_SECRET=test-secret-key-for-ci

export TEST_DATABASE_URL=postgres://postgres:dummypassword1234@localhost:5432/test_db

```

Add to `.env` file or shell profile for persistence.

Development Workflow

Running Locally

**Backend (port 3001):**

```bash

cd backend && npm run dev

```

Auto-reloads on file changes.

**Frontend (port 5173):**

```bash

cd frontend && npm run dev

```

Proxies `/api` requests to backend.

Code Style Enforcement

**Run linter before committing:**

```bash

npm run lint

```

**Style rules (enforced via ESLint):**

Testing Strategy

**Frontend Unit Tests (no database required):**

```bash

npm run test:frontend

```

Fast execution (~5 seconds), uses Vitest + React Testing Library.

**Backend Integration Tests (requires PostgreSQL):**

```bash

JWT_SECRET=test-secret-key-for-ci TEST_DATABASE_URL=postgres://postgres:dummypassword1234@localhost:5432/test_db npm run test:backend

```

Tests run sequentially to avoid database race conditions (~2 seconds).

**End-to-End Tests (requires PostgreSQL):**

```bash

First time only

npx playwright install --with-deps

Run tests

JWT_SECRET=test-secret-key-for-ci TEST_DATABASE_URL=postgres://postgres:dummypassword1234@localhost:5432/test_db npx playwright test

```

Automatically starts backend and frontend servers (~120 seconds total).

Building for Production

**Frontend bundle:**

```bash

cd frontend && npm run build

```

Output: `frontend/dist/` (~3 seconds)

**Backend:** No build step required (runs directly with Node.js)

CI/CD Pipeline

Triggers

Pipeline Steps

1. Install Node.js 24

2. Start PostgreSQL 18 service (Docker)

3. Install dependencies (`npm ci` in root, frontend, backend)

4. Lint (frontend + backend)

5. Backend tests (with database)

6. Frontend tests

7. Upload coverage to Codecov

8. **Conditionally** install Playwright browsers

9. **Conditionally** run E2E tests

10. Upload Playwright artifacts

Commit Message Flags

Control CI behavior with special commit tags:

**Default:** E2E tests run on all PRs but not on direct pushes to main.

Error Handling Guidelines

When adding new features, evaluate whether specific error handlers are needed in `backend/utils/middleware.js`.

**Add specific error handler if:**

1. User can fix the error (validation, auth)

2. Error is common and recurring

3. Requires specific HTTP status code (400, 401, 403)

4. Error source is stable (library/framework errors)

5. No security risk in exposing details

**Use generic handler for:**

**Examples requiring specific handlers:**

**Rule of thumb:** When in doubt, use the generic error handler. Only add specific handling for recurring, user-fixable errors.

Pre-PR Validation Checklist

Run these commands to replicate CI locally:

```bash

Install dependencies

npm ci

npm --prefix frontend ci

npm --prefix backend ci

Lint

npm run lint

Backend tests

JWT_SECRET=test-secret-key-for-ci TEST_DATABASE_URL=postgres://postgres:dummypassword1234@localhost:5432/test_db npm run test:backend

Frontend tests

npm run test:frontend

Optional: E2E tests

npx playwright install --with-deps

JWT_SECRET=test-secret-key-for-ci TEST_DATABASE_URL=postgres://postgres:dummypassword1234@localhost:5432/test_db npx playwright test

```

All commands must pass before creating a PR.

Architecture Reference

Project Structure

```

/

├── backend/ # Express.js REST API

│ ├── controllers/ # Route handlers (users, login, logout, files)

│ ├── models/ # Sequelize models (User, Session, File)

│ ├── migrations/ # Database migrations (Umzug)

│ ├── utils/ # Config, DB, middleware

│ └── tests/ # Integration & unit tests

├── frontend/ # React + Vite SPA

│ └── src/

│ ├── components/ # Login, Register, Welcome

│ ├── services/ # API service layers

│ └── tests/unit/ # Frontend unit tests

├── e2e-tests/ # Playwright E2E tests

└── package.json # Root workspace scripts

```

Key Files

Important Notes

1. **NEVER commit directly to main** - use pull requests

2. **Test parallelization disabled** for backend (prevents DB race conditions)

3. **Migrations run automatically** on backend startup

4. **File uploads** stored in `uploads/` (gitignored)

5. **Testing endpoint** `/api/testing/resetDb` only in test mode

6. **Express.js 5** conventions (not v4)

7. **Coverage tracked** via Codecov

Common Issues & Solutions

**Backend tests fail with DB connection error:**

**Playwright tests timeout:**

**Lint failures:**

When to Search for More Information

These instructions are validated and comprehensive. Only search externally if: