makefile-dev-workflow

Makefile Development Workflow

When to use

Use this skill when you need to:

• Start development services (database, backend API, frontend)
• Stop services cleanly
• Run end-to-end tests with Playwright
• Check service health status
• Build and deploy applications
• Clean build artifacts
• Manage the full development stack with a single command

Core concepts

The repository includes a unified Makefile (at repo root) that wraps complex shell commands into simple targets. This replaces scattered docker-compose commands and cargo/npm invocations with a consistent interface.

Key directories

• edgequake/: Rust backend API (port 8080)
• edgequake_webui/: Next.js frontend (port 3000)
• edgequake/docker/: Docker configuration with docker-compose.yml (contains PostgreSQL + pgvector + Apache AGE)

Quick start commands

Start full development stack (all services)

make dev

Starts PostgreSQL, Rust backend, and Next.js frontend in parallel. Displays URLs for all services.

Stop all services

make stop

Kills all running processes and stops Docker containers gracefully.

Check service status

make status

Shows health of backend, frontend, and database with actual health checks and endpoints.

Service-specific commands

Database management

make db-start     # Start PostgreSQL container (port 5432)
make db-stop      # Stop PostgreSQL gracefully
make db-logs      # View PostgreSQL logs in real-time
make db-shell     # Open psql shell into the database
make db-reset     # DANGER: Delete all data and reinitialize database

Backend (Rust) management

make backend-dev     # Run backend in development mode with hot reload
make backend-build   # Build backend for release
make backend-test    # Run backend tests (uses mock LLM provider by default)
make backend-run     # Run compiled backend binary
make backend-clippy  # Lint backend code (strict)
make backend-fmt     # Format backend code with rustfmt

Frontend (Next.js) management

make frontend-dev    # Start frontend dev server with Turbopack (hot reload)
make frontend-build  # Build frontend for production
make frontend-start  # Start production frontend server
make frontend-lint   # Lint frontend code (ESLint)
make frontend-test   # Run frontend unit tests

E2E Testing with Playwright

Run all E2E tests

cd edgequake_webui && pnpm exec playwright test

Runs all test specs in e2e/ directory with HTML reporter.

Run specific E2E test

cd edgequake_webui && pnpm exec playwright test markdown-test.spec.ts

Core query page tests

cd edgequake_webui && pnpm exec playwright test \
  markdown-test.spec.ts \
  streaming-test.spec.ts \
  live-query-test.spec.ts \
  final-validation.spec.ts

These tests verify:

• markdown-test: Markdown rendering in responses (no raw ** showing)
• streaming-test: Streaming text handling without concatenation issues
• live-query-test: End-to-end query execution with real LLM response
• final-validation: Complete query interface functionality

View test report

cd edgequake_webui && pnpm exec playwright show-report

Opens HTML report of last test run showing pass/fail, screenshots, traces.

Docker stack commands

Build all Docker images

make docker-build

Start full Docker stack (API + PostgreSQL)

make docker-up

Starts containerized EdgeQuake API and PostgreSQL with automatic health checks.

Stop Docker stack

make docker-down

View Docker logs

make docker-logs

Check Docker container status

make docker-ps

Code quality commands

Lint all code

make lint

Runs cargo clippy (Rust) and ESLint (frontend) with strict warnings-as-errors.

Format all code

make format

Applies rustfmt to Rust code and prettier to frontend code.

Run all tests

make test

Runs both backend tests (with mock LLM) and frontend tests in parallel.

Build all projects

make build

Produces release binaries for both backend and frontend.

Dependency checks

Verify dependencies

make check-deps

Verifies that required tools are installed:

• cargo (Rust toolchain)
• bun or npm (Node.js)
• docker (optional, required for db-start/Docker commands)

If dependencies are missing, installation instructions are provided.

Installation

Install all dependencies

make install

Installs Rust crates and frontend npm packages.

Cleanup

Clean build artifacts

make clean

Removes target/ directory and .next/ build caches.

Clean everything (including dependencies)

make clean-all

Also removes node_modules/ - forces full reinstall on next run.

Utilities

Open Swagger UI

make swagger

Opens browser to http://localhost:8080/swagger-ui (API documentation).

View recent logs

make logs

Shows recent backend logs and Docker container status.

Common workflows

Development workflow

# 1. Install dependencies
make install

# 2. Start full stack
make dev

# 3. Make changes to code...

# 4. Check code quality before committing
make lint
make format
make test

# 5. Run E2E tests to verify UI
cd edgequake_webui && pnpm exec playwright test

# 6. Stop when done
make stop

Testing workflow

# Start database (for integration tests)
make db-start

# Run backend tests
make backend-test

# Run frontend tests
make frontend-test

# Run E2E tests
cd edgequake_webui && pnpm exec playwright test markdown-test.spec.ts

# View results
make status

Production build workflow

# Build both projects
make build

# Start Docker stack with built images
make docker-up

# Check it's healthy
make status

# Stop when done
make docker-down

Service URLs

Service	URL	Purpose
Frontend	http://localhost:3000	Main application UI
Backend API	http://localhost:8080	REST API endpoints
Swagger UI	http://localhost:8080/swagger-ui	API documentation
Database	localhost:5432	PostgreSQL with pgvector/AGE

Environment variables

Configure these in .env file (copy from .env.example):

# LLM Provider (auto-detected from this)
OPENAI_API_KEY=sk-...

# Database (defaults to Docker PostgreSQL)
DATABASE_URL=postgres://edgequake:edgequake_secret@localhost:5432/edgequake

# Server config
EDGEQUAKE_PORT=8080
EDGEQUAKE_HOST=0.0.0.0

# Logging
RUST_LOG=info,edgequake=debug

Without OPENAI_API_KEY, the system uses a mock LLM provider (free, fast, no API key).

Troubleshooting

Port already in use

If port 3000 or 8080 is in use:

# Kill existing process on port 3000
lsof -ti :3000 | xargs kill -9

# Kill existing process on port 8080
lsof -ti :8080 | xargs kill -9

Database connection issues

# Reset database (deletes all data!)
make db-reset

# Check if database is accepting connections
make status

Frontend build issues

# Clean and reinstall
make clean-all
make install
make frontend-dev

Tests timing out

# Increase Playwright timeout in playwright.config.ts
# Or run tests with more time:
cd edgequake_webui && pnpm exec playwright test --timeout=60000

Implementation notes

• No docker-compose.yml at root: Use edgequake/docker/docker-compose.yml instead
• Package manager: Frontend uses pnpm (fast, space-efficient) but falls back to npm
• Rust hot reload: Uses cargo run for development (recompiles on save)
• Next.js dev: Uses Turbopack for faster iterations than Webpack
• Port isolation: Services communicate via localhost ports; no environment routing needed

Help

make help

Shows formatted help with all available targets and descriptions.

---

Related Skills

• playwright-ux-ui-capture: Using Playwright to capture screenshots and artifacts
• ux-ui-analyze-single-page: Analyzing individual pages with Playwright