xpeditis2.0/QUICK-START.md

# 🚀 Quick Start Guide - Xpeditis

Get the Xpeditis maritime freight booking platform running in **5 minutes**.

---

## Prerequisites

Before you begin, ensure you have:

- ✅ **Node.js** v20+ ([Download](https://nodejs.org/))
- ✅ **npm** v10+ (comes with Node.js)
- ✅ **Docker Desktop** ([Download](https://www.docker.com/products/docker-desktop/))
- ✅ **Git** ([Download](https://git-scm.com/))

---

## Step 1: Clone & Install (2 minutes)

```bash
# Clone the repository
cd xpeditis2.0

# Install all dependencies
npm install

# This will install:
# - Root workspace dependencies
# - Backend dependencies (~50 packages)
# - Frontend dependencies (~30 packages)
```

**Note**: If you encounter `EISDIR` errors on Windows, it's okay - the dependencies are still installed correctly.

---

## Step 2: Start Infrastructure (1 minute)

```bash
# Start PostgreSQL + Redis with Docker
docker-compose up -d

# Verify containers are running
docker-compose ps

# You should see:
# ✅ xpeditis-postgres (port 5432)
# ✅ xpeditis-redis (port 6379)
```

---

## Step 3: Configure Environment (1 minute)

```bash
# Backend
cp apps/backend/.env.example apps/backend/.env

# Frontend
cp apps/frontend/.env.example apps/frontend/.env
```

**The default `.env` values work for local development!** No changes needed to get started.

---

## Step 4: Start Development Servers (1 minute)

### Option A: Two Terminals

```bash
# Terminal 1 - Backend
cd apps/backend
npm run dev

# Terminal 2 - Frontend
cd apps/frontend
npm run dev
```

### Option B: Root Commands

```bash
# Terminal 1 - Backend
npm run backend:dev

# Terminal 2 - Frontend
npm run frontend:dev
```

---

## Step 5: Verify Everything Works

### Backend ✅

Open: **http://localhost:4000/api/v1/health**

Expected response:
```json
{
  "status": "ok",
  "timestamp": "2025-10-07T...",
  "uptime": 12.345,
  "environment": "development",
  "version": "0.1.0"
}
```

### API Documentation ✅

Open: **http://localhost:4000/api/docs**

You should see the Swagger UI with:
- Health endpoints
- (More endpoints will be added in Phase 1)

### Frontend ✅

Open: **http://localhost:3000**

You should see:
```
🚢 Xpeditis
Maritime Freight Booking Platform
Search, compare, and book maritime freight in real-time
```

---

## 🎉 Success!

You now have:
- ✅ Backend API running on port 4000
- ✅ Frontend app running on port 3000
- ✅ PostgreSQL database on port 5432
- ✅ Redis cache on port 6379
- ✅ Swagger API docs available
- ✅ Hot reload enabled for both apps

---

## Common Commands

### Development

```bash
# Backend
npm run backend:dev          # Start backend dev server
npm run backend:test         # Run backend tests
npm run backend:test:watch   # Run tests in watch mode
npm run backend:lint         # Lint backend code

# Frontend
npm run frontend:dev         # Start frontend dev server
npm run frontend:build       # Build for production
npm run frontend:test        # Run frontend tests
npm run frontend:lint        # Lint frontend code

# Both
npm run format               # Format all code
npm run format:check         # Check formatting
npm run test:all             # Run all tests
```

### Infrastructure

```bash
# Docker
docker-compose up -d         # Start services
docker-compose down          # Stop services
docker-compose logs -f       # View logs
docker-compose ps            # Check status

# Database
docker-compose exec postgres psql -U xpeditis -d xpeditis_dev

# Redis
docker-compose exec redis redis-cli -a xpeditis_redis_password
```

---

## Troubleshooting

### Port Already in Use

```bash
# Backend (port 4000)
# Windows: netstat -ano | findstr :4000
# Mac/Linux: lsof -i :4000

# Frontend (port 3000)
# Windows: netstat -ano | findstr :3000
# Mac/Linux: lsof -i :3000
```

### Docker Not Starting

```bash
# Check Docker is running
docker --version

# Restart Docker Desktop
# Then retry: docker-compose up -d
```

### Database Connection Issues

```bash
# Check PostgreSQL is running
docker-compose ps

# View PostgreSQL logs
docker-compose logs postgres

# Restart PostgreSQL
docker-compose restart postgres
```

### npm Install Errors

```bash
# Clear cache and retry
npm cache clean --force
rm -rf node_modules
npm install
```

---

## Next Steps

### 📚 Read the Documentation

- [README.md](README.md) - Full project documentation
- [CLAUDE.md](CLAUDE.md) - Hexagonal architecture guidelines
- [TODO.md](TODO.md) - 30-week development roadmap
- [SPRINT-0-FINAL.md](SPRINT-0-FINAL.md) - Sprint 0 completion report

### 🛠️ Start Building

Ready to start Phase 1? Check out [TODO.md](TODO.md) for the roadmap:

- **Sprint 1-2**: Domain entities and ports
- **Sprint 3-4**: Infrastructure and database
- **Sprint 5-6**: Rate search API
- **Sprint 7-8**: Rate search UI

### 🧪 Run Tests

```bash
# Backend unit tests
cd apps/backend
npm test

# Backend E2E tests
npm run test:e2e

# Frontend tests
cd apps/frontend
npm test
```

### 🔍 Explore the Code

**Hexagonal Architecture**:
```
apps/backend/src/
├── domain/           # Pure business logic (start here!)
├── application/      # Controllers & DTOs
└── infrastructure/   # External adapters
```

**Frontend Structure**:
```
apps/frontend/
├── app/             # Next.js App Router
├── components/      # React components
└── lib/             # Utilities
```

---

## 🎯 You're Ready!

The Xpeditis development environment is fully set up and ready for Phase 1 development.

**Happy coding! 🚀**

---

## Need Help?

- 📖 Check [README.md](README.md) for detailed documentation
- 🏗️ Review [CLAUDE.md](CLAUDE.md) for architecture guidelines
- 📝 Follow [TODO.md](TODO.md) for the development roadmap
- ❓ Open an issue on GitHub

---

*Xpeditis - Maritime Freight Booking Platform*