xpeditis2.0/docs/installation/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)
• ✅ npm v10+ (comes with Node.js)
• ✅ Docker Desktop (Download)
• ✅ Git (Download)

---

Step 1: Clone & Install (2 minutes)

# 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)

# 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)

# 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

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

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

Option B: Root Commands

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

{
  "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

# 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

# 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

# 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

# Check Docker is running
docker --version

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

Database Connection Issues

# Check PostgreSQL is running
docker-compose ps

# View PostgreSQL logs
docker-compose logs postgres

# Restart PostgreSQL
docker-compose restart postgres

npm Install Errors

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

---

Next Steps

📚 Read the Documentation

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

🛠️ Start Building

Ready to start Phase 1? Check out 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

# 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 for detailed documentation
• 🏗️ Review CLAUDE.md for architecture guidelines
• 📝 Follow TODO.md for the development roadmap
• ❓ Open an issue on GitHub

---

Xpeditis - Maritime Freight Booking Platform