mtg-search/DEVELOPMENT.md

Development Guide for MTG Search

Local Development Environment Setup

Prerequisites Installation

macOS

# Install Homebrew if not already installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Java 21
brew install --cask java

# Install Node.js
brew install node@20

# Install PostgreSQL
brew install postgresql

# Install Docker
brew install --cask docker

Ubuntu/Debian

# Install Java 21
sudo apt-get update
sudo apt-get install -y openjdk-21-jdk

# Install Node.js
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Install PostgreSQL
sudo apt-get install -y postgresql postgresql-contrib

# Install Docker
curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker $USER

Windows

1. Install Java 21 from Oracle
2. Install Node.js from nodejs.org
3. Install PostgreSQL from postgresql.org
4. Install Docker Desktop from docker.com

Quick Start with Startup Script

# Make script executable
chmod +x startup.sh

# Run the startup script
./startup.sh

Manual Setup

Step 1: Start PostgreSQL

Using Docker (Recommended):

docker run --name mtgsearch-postgres \
  -e POSTGRES_DB=mtgsearch \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=postgres \
  -p 5432:5432 \
  -d postgres:17-alpine

Using Local PostgreSQL:

# macOS
brew services start postgresql

# Linux
sudo systemctl start postgresql

# Windows
# Start from Services or GUI

Step 2: Verify Database Connection

psql -U postgres -h localhost -d mtgsearch -c "SELECT 1;"

Step 3: Build and Run Backend

cd backend

# Build with Gradle
../gradlew build

# Run the application
../gradlew bootRun

# The backend will start on http://localhost:8080

Step 4: Set Up and Run Frontend

cd frontend

# Install dependencies
npm install

# Start development server
npm run dev

# The frontend will start on http://localhost:5173

Development Workflow

Making Changes

Backend Changes

1. Edit Java files in backend/src/main/java
2. Spring Boot DevTools will auto-reload
3. Check logs: tail -f logs/mtg-search.log

Frontend Changes

1. Edit Vue files in frontend/src
2. Vite will hot-reload automatically
3. Check browser console for errors

Testing

Backend Tests

cd backend

# Run all tests
../gradlew test

# Run specific test class
../gradlew test --tests AuthServiceTest

# Run with coverage
../gradlew test jacocoTestReport

Frontend Tests

cd frontend

# Run tests
npm run test

# Run with coverage
npm run test -- --coverage

# Watch mode
npm run test -- --watch

Code Quality

Backend

cd backend

# Run checks (spotless, checkstyle, etc.)
../gradlew check

# Format code
../gradlew spotlessApply

Frontend

cd frontend

# Run linter
npm run lint

# Fix linting issues
npm run lint --fix

Database Management

Running Flyway Migrations

Migrations run automatically when the application starts. To manage migrations manually:

cd backend

# Show migration status
../gradlew flywayInfo

# Validate migrations
../gradlew flywayValidate

# Repair (use with caution)
../gradlew flywayRepair

# Clean schema (WARNING: deletes all data)
../gradlew flywayClean

Creating New Migration

1. Create file: backend/src/main/resources/db/migration/V{NUMBER}__Description.sql

Example:

-- V2__Add_search_history_table.sql
CREATE TABLE IF NOT EXISTS search_history (
    id BIGSERIAL PRIMARY KEY,
    user_id BIGINT NOT NULL REFERENCES users(id),
    search_query VARCHAR(255) NOT NULL,
    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
);

CREATE INDEX idx_search_history_user_id ON search_history(user_id);

API Endpoints Testing

Using curl

# Register a new user
curl -X POST http://localhost:8080/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "testuser",
    "email": "test@example.com",
    "password": "SecurePassword123!"
  }'

# Login
curl -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "testuser",
    "password": "SecurePassword123!"
  }'

# Use token in requests
TOKEN=<your-jwt-token>
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8080/api/v1/protected-endpoint

Using Swagger UI

Navigate to: http://localhost:8080/swagger-ui.html

Debugging

Backend Debugging

In IDE (IntelliJ IDEA)

1. Set breakpoints in your code
2. Run → Debug 'MtgSearchApplication'
3. Step through code

Remote Debugging

cd backend
../gradlew bootRun --args='--debug'

# Then connect remote debugger on port 5005

Frontend Debugging

1. Open browser DevTools (F12 or Cmd+Option+I)
2. Check Console, Network, and Application tabs
3. Use Vue DevTools browser extension

Logs

# Backend logs
tail -f logs/mtg-search.log

# Backend errors
tail -f logs/mtg-search-error.log

# Frontend browser console
# Open DevTools → Console tab

Environment Variables

Create .env file in project root:

# Database
DB_URL=jdbc:postgresql://localhost:5432/mtgsearch
DB_USER=postgres
DB_PASSWORD=postgres

# JWT
JWT_SECRET=development-secret-key
JWT_EXPIRATION=86400

# Application
SPRING_PROFILE=dev

# Frontend
VITE_API_URL=http://localhost:8080

IDE Configuration

IntelliJ IDEA

1. Open project root folder
2. File → Project Structure → Modules
3. Select backend module
4. Set Java 21 as SDK
5. Install Spring Boot plugin
6. Install Lombok plugin

VS Code

1. Install extensions:
   • Extension Pack for Java
   • Spring Boot Extension Pack
   • Vue 3 Extension
   • TypeScript Vue Plugin
2. Configure Java home in settings
3. Install Node modules

Useful Gradle Commands

# Build tasks
./gradlew build              # Full build
./gradlew clean build        # Clean and build
./gradlew build -x test      # Build without tests

# Test tasks
./gradlew test               # Run tests
./gradlew test --watch       # Watch mode

# Development tasks
./gradlew bootRun            # Run application
./gradlew bootRun --debug    # Debug mode

# Code generation
./gradlew openApiGenerate    # Generate from OpenAPI spec
./gradlew generateJooqCode   # Generate jOOQ entities

# Database tasks
./gradlew flywayInfo         # Show migration status
./gradlew flywayMigrate      # Run migrations

Useful npm Commands

# Development
npm run dev              # Start dev server
npm run build            # Build for production
npm run preview          # Preview production build

# Testing
npm run test             # Run tests
npm run test:ui          # Run tests with UI
npm run test -- --watch  # Watch mode

# Quality
npm run lint             # Run linter
npm run type-check       # Check TypeScript types

Troubleshooting Common Issues

"Address already in use" port 8080

# Find process using port 8080
lsof -i :8080

# Kill the process
kill -9 <PID>

"Address already in use" port 5173

# Find process using port 5173
lsof -i :5173

# Kill the process
kill -9 <PID>

PostgreSQL connection refused

# Check if PostgreSQL is running
psql --version

# Try to connect
psql -U postgres -h localhost

# If using Docker, check container
docker ps | grep postgres
docker logs mtgsearch-postgres

Gradle build fails

# Clear gradle cache
rm -rf ~/.gradle/caches

# Clean and rebuild
./gradlew clean build --refresh-dependencies

Frontend build fails

# Clear node_modules
rm -rf frontend/node_modules package-lock.json

# Reinstall dependencies
cd frontend && npm install

Flyway migration fails

# Check migration status
cd backend && ../gradlew flywayInfo

# Validate migrations
../gradlew flywayValidate

# Start fresh (DELETES ALL DATA)
../gradlew flywayClean
../gradlew flywayMigrate

Performance Profiling

Backend

# Generate JFR recording
cd backend
../gradlew bootRun --jvmArgs="-XX:StartFlightRecording=filename=recording.jfr"

# Analyze with Java Flight Recorder
jmc recording.jfr

Frontend

# Build with source maps
cd frontend
npm run build -- --sourcemap

# Use Chrome DevTools Performance tab

Additional Resources

• Spring Boot Documentation
• Vue 3 Documentation
• PostgreSQL Documentation
• Gradle Documentation
• Docker Documentation
• GitLab CI/CD Documentation