# 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](START-HERE.md)** ⭐

**New to the project?** Read **[START-HERE.md](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

```bash
# 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](CLAUDE.md) for detailed architecture guidelines.

## 🛠️ Development

### Backend

```bash
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

```bash
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](QUICK-START.md)** ⚡ - Get running in 5 minutes
- **[INSTALLATION-STEPS.md](INSTALLATION-STEPS.md)** 📦 - Detailed installation guide
- **[NEXT-STEPS.md](NEXT-STEPS.md)** 🚀 - What to do after setup

### Architecture & Guidelines
- **[CLAUDE.md](CLAUDE.md)** 🏗️ - Hexagonal architecture guidelines (complete)
- **[apps/backend/README.md](apps/backend/README.md)** - Backend documentation
- **[apps/frontend/README.md](apps/frontend/README.md)** - Frontend documentation

### Project Planning
- **[PRD.md](PRD.md)** 📋 - Product Requirements Document
- **[TODO.md](TODO.md)** 📅 - 30-week development roadmap
- **[SPRINT-0-FINAL.md](SPRINT-0-FINAL.md)** ✅ - Sprint 0 completion report
- **[SPRINT-0-SUMMARY.md](SPRINT-0-SUMMARY.md)** 📊 - Executive summary

### API Documentation
- **[API Docs](http://localhost:4000/api/docs)** 📖 - OpenAPI/Swagger (when running)

## 🧪 Testing

```bash
# 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](CLAUDE.md).