Getting Started & Local Setup
Relevant source files
The following files were used as context for generating this wiki page:
The WhereIsLifeCheaper project is a multi-country grocery price comparison system designed to track cost-of-living data by scraping supermarket websites daily. This guide provides the necessary steps to configure the local development environment, including database initialization, dependency management, and service execution. Sources: README.md:1-5, CLAUDE.md:3-6
Prerequisites
Before beginning the setup, ensure the following software is installed on your local machine:
- Node.js 18+: The primary runtime for both the backend and frontend. Sources: CLAUDE.md:12, README.md:41
- Docker & Docker Compose: Required for running the PostgreSQL 15 database instance. Sources: CLAUDE.md:15, README.md:42
- Git: For repository cloning and version control. Sources: README.md:43
Initial Configuration
The setup follows a specific sequence to ensure the database is accessible and the application environment is correctly populated. Sources: CLAUDE.md:54-60, README.md:47-75
Step 1: Repository & Dependencies
Clone the repository and install the required Node.js packages for both the root (backend/scripts) and the frontend directory.
git clone <repository-url>
cd whereislifecheaper
npm install
cd frontend && npm install && cd ..
Sources: README.md:47-51
Step 2: Playwright Installation
The system uses Playwright (Chromium) for web scraping. The browser binaries must be installed manually.
npx playwright install chromium
Sources: CLAUDE.md:58, README.md:54
Step 3: Environment Variables
Copy the example environment file and configure it with your local credentials.
cp .env.example .env
Sources: README.md:57-58
| Variable | Description | Requirement |
|---|---|---|
DATABASE_URL | PostgreSQL connection string | Required |
SESSION_SECRET | Secret key for express sessions | Required |
API_PORT | Port for the Express server (Default: 3000) | Optional |
PLAYWRIGHT_HEADLESS | Run scrapers without a GUI (Default: true) | Optional |
LOG_LEVEL | Winston logging level (error, warn, info, debug) | Optional |
Sources: CLAUDE.md:118-124, README.md:119-127
Database Setup
The project relies on a PostgreSQL 15 container for persistent storage of product mappings, prices, and scrape logs. Sources: CLAUDE.md:15, plan.md:104-121
Launching the Database
The docker-compose.yml file defines the PostgreSQL service and an optional pgAdmin instance.
docker-compose up -d
Sources: CLAUDE.md:51-53, README.md:61
Migrations and Seeding
Once the database is running, execute the migration and seed scripts to create the schema and populate initial data (countries, categories, and supermarkets).
npm run migrate
npm run seed
Sources: CLAUDE.md:59-60, README.md:64-65
The following diagram illustrates the initial setup and data flow during the local environment preparation:
This flow represents the dependency chain required to transition from a clean clone to a functional local environment. Sources: CLAUDE.md:54-62, README.md:47-65
Running the Application
The system is split into three main operational modes: the API server, the Frontend dashboard, and the Scraper engine. Sources: CLAUDE.md:66-72, README.md:68-75
Development Servers
Run the backend API and frontend React application simultaneously during development.
# Terminal 1: Backend API
npm run api
# Terminal 2: Frontend
npm run dev:frontend
- Backend API: Accessible at
http://localhost:3000Sources: src/api/server.ts:153 - Frontend Dashboard: Accessible at
http://localhost:5173Sources: src/api/server.ts:154
Scraper Execution
Scrapers can be triggered manually for testing or run in bulk.
# Run all registered scrapers
npm run scraper:run
# Test a specific scraper (e.g., Migros)
npm run scraper:test -- MigrosScraper
Sources: CLAUDE.md:69-70, scripts/test-scrapers.ts:14-23
Common NPM Scripts Reference
| Script | Command | Purpose |
|---|---|---|
build | tsc && npm run build:frontend | Compiles TS and builds React app |
dev | ts-node src/api/server.ts | Runs backend with hot-reloading |
test | jest | Executes the test suite |
rates:sync | ts-node scripts/sync-exchange-rates.ts | Updates currency data |
Sources: package.json:7-24
Architecture Overview
The system architecture is designed for modularity, allowing new countries and supermarkets to be added by extending the BaseScraper. Sources: CLAUDE.md:21-42, plan.md:14-25
The interaction between the components ensures that the data scraped from supermarket websites is persisted in PostgreSQL and served to the user through the React frontend via the Express REST API. Sources: CLAUDE.md:22-38, plan.md:15-24
Conclusion
Setting up the WhereIsLifeCheaper environment requires local database orchestration and specific browser binary installation via Playwright. Once configured, developers can use the provided scripts to manage schema changes, seed data, and execute scrapers to build a historical price database. Sources: CLAUDE.md:137-142, plan.md:273-280