mtg-search/DEVELOPMENT.md

# Development Guide for MTG Search

## Local Development Environment Setup

### Prerequisites Installation

#### macOS
```bash
# 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
```bash
# 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](https://www.oracle.com/java/technologies/downloads/)
2. Install Node.js from [nodejs.org](https://nodejs.org)
3. Install PostgreSQL from [postgresql.org](https://www.postgresql.org/download/windows/)
4. Install Docker Desktop from [docker.com](https://www.docker.com/products/docker-desktop)

### Quick Start with Startup Script

```bash
# Make script executable
chmod +x startup.sh

# Run the startup script
./startup.sh
```

### Manual Setup

#### Step 1: Start PostgreSQL

**Using Docker (Recommended):**
```bash
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:**
```bash
# macOS
brew services start postgresql

# Linux
sudo systemctl start postgresql

# Windows
# Start from Services or GUI
```

#### Step 2: Verify Database Connection

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

#### Step 3: Build and Run Backend

```bash
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

```bash
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
```bash
cd backend

# Run all tests
../gradlew test

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

# Run with coverage
../gradlew test jacocoTestReport
```

#### Frontend Tests
```bash
cd frontend

# Run tests
npm run test

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

# Watch mode
npm run test -- --watch
```

### Code Quality

#### Backend
```bash
cd backend

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

# Format code
../gradlew spotlessApply
```

#### Frontend
```bash
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:

```bash
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:
```sql
-- 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

```bash
# 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
```bash
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

```bash
# 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:

```env
# 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

```bash
# 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

```bash
# 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
```bash
# Find process using port 8080
lsof -i :8080

# Kill the process
kill -9 <PID>
```

### "Address already in use" port 5173
```bash
# Find process using port 5173
lsof -i :5173

# Kill the process
kill -9 <PID>
```

### PostgreSQL connection refused
```bash
# 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
```bash
# Clear gradle cache
rm -rf ~/.gradle/caches

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

### Frontend build fails
```bash
# Clear node_modules
rm -rf frontend/node_modules package-lock.json

# Reinstall dependencies
cd frontend && npm install
```

### Flyway migration fails
```bash
# Check migration status
cd backend && ../gradlew flywayInfo

# Validate migrations
../gradlew flywayValidate

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

## Performance Profiling

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

# Analyze with Java Flight Recorder
jmc recording.jfr
```

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

# Use Chrome DevTools Performance tab
```

## Additional Resources

- [Spring Boot Documentation](https://spring.io/projects/spring-boot)
- [Vue 3 Documentation](https://vuejs.org)
- [PostgreSQL Documentation](https://www.postgresql.org/docs/)
- [Gradle Documentation](https://gradle.org/guides/)
- [Docker Documentation](https://docs.docker.com/)
- [GitLab CI/CD Documentation](https://docs.gitlab.com/ee/ci/)