Xpeditis - Maritime Freight Booking Platform

Xpeditis is a B2B SaaS platform for freight forwarders to search, compare, and book maritime freight in real-time.

---

⭐ START HERE ⭐

New to the project? Read START-HERE.md - Get running in 10 minutes!

---

🚀 Quick Start

Prerequisites

• Node.js >= 20.0.0
• npm >= 10.0.0
• Docker & Docker Compose
• PostgreSQL 15+
• Redis 7+

Installation

# Install dependencies
npm install

# Start infrastructure (PostgreSQL + Redis)
docker-compose up -d

# Setup environment variables
cp apps/backend/.env.example apps/backend/.env
cp apps/frontend/.env.example apps/frontend/.env

# Run database migrations
npm run backend:migrate

# Start backend (development)
npm run backend:dev

# Start frontend (development)
npm run frontend:dev

Access Points

• Frontend: http://localhost:3000
• Backend API: http://localhost:4000
• API Documentation: http://localhost:4000/api/docs

📁 Project Structure

xpeditis/
├── apps/
│   ├── backend/          # NestJS API (Hexagonal Architecture)
│   │   └── src/
│   │       ├── domain/          # Pure business logic
│   │       ├── application/     # Controllers & DTOs
│   │       └── infrastructure/  # External adapters
│   └── frontend/         # Next.js 14 App Router
├── packages/
│   ├── shared-types/     # Shared TypeScript types
│   └── domain/           # Shared domain logic
└── infra/                # Infrastructure configs

🏗️ Architecture

This project follows Hexagonal Architecture (Ports & Adapters) principles:

• Domain Layer: Pure business logic, no external dependencies
• Application Layer: Use cases, controllers, DTOs
• Infrastructure Layer: Database, external APIs, cache, email, storage

See CLAUDE.md for detailed architecture guidelines.

🛠️ Development

Backend

npm run backend:dev          # Start dev server
npm run backend:test         # Run tests
npm run backend:test:watch   # Run tests in watch mode
npm run backend:test:cov     # Generate coverage report
npm run backend:lint         # Lint code
npm run backend:build        # Build for production

Frontend

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

📚 Documentation

Getting Started

• QUICK-START.md ⚡ - Get running in 5 minutes
• INSTALLATION-STEPS.md 📦 - Detailed installation guide
• NEXT-STEPS.md 🚀 - What to do after setup

Architecture & Guidelines

• CLAUDE.md 🏗️ - Hexagonal architecture guidelines (complete)
• apps/backend/README.md - Backend documentation
• apps/frontend/README.md - Frontend documentation

Project Planning

• PRD.md 📋 - Product Requirements Document
• TODO.md 📅 - 30-week development roadmap
• SPRINT-0-FINAL.md ✅ - Sprint 0 completion report
• SPRINT-0-SUMMARY.md 📊 - Executive summary

API Documentation

• API Docs 📖 - OpenAPI/Swagger (when running)

🧪 Testing

# Run all tests
npm run test:all

# Run backend tests
npm run backend:test

# Run frontend tests
npm run frontend:test

# E2E tests (after implementation)
npm run test:e2e

🔒 Security

• All passwords hashed with bcrypt (12 rounds minimum)
• JWT tokens (access: 15min, refresh: 7 days)
• HTTPS/TLS 1.2+ enforced
• OWASP Top 10 protection
• Rate limiting on all endpoints
• CSRF protection

📊 Tech Stack

Backend

• Framework: NestJS 10+
• Language: TypeScript 5+
• Database: PostgreSQL 15+
• Cache: Redis 7+
• ORM: TypeORM
• Testing: Jest, Supertest
• API Docs: Swagger/OpenAPI

Frontend

• Framework: Next.js 14+ (App Router)
• Language: TypeScript 5+
• Styling: Tailwind CSS
• UI Components: shadcn/ui
• State: React Query (TanStack Query)
• Forms: React Hook Form + Zod
• Testing: Jest, React Testing Library, Playwright

🚢 Carrier Integrations

MVP supports the following maritime carriers:

• ✅ Maersk
• ✅ MSC
• ✅ CMA CGM
• ✅ Hapag-Lloyd
• ✅ ONE (Ocean Network Express)

📈 Monitoring & Logging

• Logging: Winston / Pino
• Error Tracking: Sentry
• APM: Application Performance Monitoring
• Metrics: Prometheus (planned)

🔧 Environment Variables

See .env.example files in each app for required environment variables.

🤝 Contributing

1. Create a feature branch
2. Make your changes
3. Write tests
4. Run linting and formatting
5. Submit a pull request

📝 License

Proprietary - All rights reserved

👥 Team

Built with ❤️ by the Xpeditis team

---

For detailed implementation guidelines, see CLAUDE.md.