Documentation

Complete guide to the World of Books Explorer platform.

Quick Start

Get the project running in minutes:

# Clone the repository
git clone <repo-url>
cd product-explorer

# Set up environment
cp .env.example .env

# Start with Docker
docker-compose up -d

# Or run manually
cd backend && npm install && npm run start:dev
cd frontend && npm install && npm run dev

API Documentation

Key endpoints available:

GET /api/navigation - Get all navigation items
GET /api/categories - Get categories
GET /api/products - Get products
POST /api/scrape/navigation - Trigger navigation scrape
POST /api/scrape/product/:id - Refresh product data

Database Schema

Main entities in PostgreSQL:

navigation - Top-level navigation items
category - Categories with parent-child relationships
product - Product information
product_detail - Extended product details
review - Customer reviews
scrape_job - Scraping job tracking
view_history - User browsing history

Ethical Scraping

We follow strict ethical scraping practices:

• Respect robots.txt and terms of service
• Implement rate limiting (3-second delays)
• Cache results for 24 hours
• Use exponential backoff for retries
• Set proper User-Agent headers
• Queue long-running jobs

Deployment

Deploy to production:

Frontend (Vercel):

# Build command
npm run build

# Environment variables
NEXT_PUBLIC_API_URL=https://your-backend.railway.app

Backend (Railway):

# Start command
npm run start:prod

# Required services
- PostgreSQL
- Redis
- Environment variables from .env

Development

Development scripts:

npm run dev - Start development server
npm run build - Build for production
npm run test - Run tests
npm run lint - Check code quality
npm run type-check - TypeScript validation

Project Structure

product-explorer/
├── backend/                    # NestJS backend
│   ├── src/
│   │   ├── modules/           # Feature modules
│   │   ├── entities/          # TypeORM entities
│   │   └── main.ts           # Application entry
│   ├── database/             # Schema and migrations
│   └── test/                 # Backend tests
├── frontend/                  # Next.js frontend
│   ├── src/
│   │   ├── app/              # App router pages
│   │   ├── components/       # React components
│   │   ├── lib/              # Utilities and hooks
│   │   └── providers/        # Context providers
│   ├── cypress/              # E2E tests
│   └── public/               # Static assets
├── .github/workflows/        # CI/CD pipelines
├── docker-compose.yml        # Local development
└── README.md                 # Project documentation