# Xpeditis Backend API

NestJS-based API for the Xpeditis maritime freight booking platform, built with **Hexagonal Architecture**.

## 🏗️ Architecture

This backend follows **Hexagonal Architecture** (Ports & Adapters pattern):

```
src/
├── domain/              # 🔵 Pure business logic (NO external dependencies)
│   ├── entities/       # Business entities
│   ├── value-objects/  # Value objects (Email, PortCode, etc.)
│   ├── services/       # Domain services
│   ├── ports/
│   │   ├── in/        # API Ports (use cases exposed by domain)
│   │   └── out/       # SPI Ports (interfaces required by domain)
│   └── exceptions/    # Business exceptions
│
├── application/         # 🟢 Controllers & DTOs
│   ├── controllers/    # REST controllers
│   ├── dto/           # Data Transfer Objects
│   ├── mappers/       # DTO ↔ Domain mappers
│   └── config/        # Application configuration
│
└── infrastructure/      # 🟡 External integrations
    ├── persistence/    # TypeORM repositories
    ├── cache/         # Redis cache adapter
    ├── carriers/      # Maersk, MSC, CMA CGM connectors
    ├── email/         # Email service adapter
    ├── storage/       # S3 storage adapter
    └── config/        # Infrastructure configuration
```

### Key Principles

1. **Domain is isolated**: No imports of NestJS, TypeORM, or any framework in domain layer
2. **Dependencies point inward**: Infrastructure → Application → Domain
3. **Testable**: Domain can be tested without any framework
4. **Flexible**: Change database, framework, or external services without touching domain

## 🚀 Quick Start

### Prerequisites

- Node.js 20+
- PostgreSQL 15+
- Redis 7+
- Docker (optional, for local development)

### Install Dependencies

```bash
npm install
```

### Setup Environment

```bash
cp .env.example .env
# Edit .env with your configuration
```

### Start Development Server

```bash
npm run dev
```

Server runs on: **http://localhost:4000**

API Documentation: **http://localhost:4000/api/docs**

## 📝 Available Scripts

### Development

- `npm run dev` - Start development server with hot reload
- `npm run start` - Start server
- `npm run start:debug` - Start with debugging
- `npm run build` - Build for production
- `npm run start:prod` - Start production server

### Testing

- `npm test` - Run unit tests
- `npm run test:watch` - Run tests in watch mode
- `npm run test:cov` - Run tests with coverage
- `npm run test:e2e` - Run end-to-end tests
- `npm run test:debug` - Debug tests

### Code Quality

- `npm run lint` - Lint code
- `npm run format` - Format code with Prettier

### Database

- `npm run migration:generate -- src/infrastructure/persistence/migrations/MigrationName` - Generate migration
- `npm run migration:run` - Run migrations
- `npm run migration:revert` - Revert last migration

## 🔑 Environment Variables

See `.env.example` for all available variables.

**Required**:
- `DATABASE_HOST`, `DATABASE_PORT`, `DATABASE_USER`, `DATABASE_PASSWORD`, `DATABASE_NAME`
- `REDIS_HOST`, `REDIS_PORT`, `REDIS_PASSWORD`
- `JWT_SECRET`

**Optional** (for production):
- OAuth credentials (Google, Microsoft)
- Carrier API keys (Maersk, MSC, CMA CGM, etc.)
- AWS S3 credentials
- Email service credentials
- Sentry DSN

## 📚 API Documentation

Swagger/OpenAPI documentation is available at `/api/docs` when the server is running.

**Endpoints**:

### Health
- `GET /api/v1/health` - Health check
- `GET /api/v1/health/ready` - Readiness check
- `GET /api/v1/health/live` - Liveness check

### (More endpoints will be added in Phase 1)

## 🧪 Testing

### Unit Tests

Test domain logic without any external dependencies:

```bash
npm test
```

**Example** (`domain/services/booking.service.spec.ts`):
```typescript
describe('BookingService', () => {
  it('should create booking with valid rate quote', () => {
    const service = new BookingService(mockRepository);
    const result = service.createBooking(validInput);
    expect(result.bookingNumber).toMatch(/^WCM-\d{4}-[A-Z0-9]{6}$/);
  });
});
```

### Integration Tests

Test infrastructure adapters with real dependencies:

```bash
npm run test:e2e
```

### Coverage

```bash
npm run test:cov
```

**Targets**:
- Domain: 90%+
- Application: 80%+
- Infrastructure: 70%+

## 🏛️ Hexagonal Architecture Guidelines

### ✅ DO

- **Domain layer**:
  - Pure TypeScript classes
  - Define interfaces (ports)
  - Implement business logic
  - Throw domain exceptions

- **Application layer**:
  - Import from `@domain/*` only
  - Validate DTOs
  - Map DTOs ↔ Domain entities
  - Handle HTTP-specific concerns

- **Infrastructure layer**:
  - Import from `@domain/*` only
  - Implement port interfaces
  - Handle framework-specific code
  - Map ORM entities ↔ Domain entities

### ❌ DON'T

- Import NestJS decorators in domain
- Import TypeORM in domain
- Put business logic in controllers
- Put business logic in repositories
- Use `any` type
- Skip tests

## 🔒 Security

- Passwords hashed with bcrypt (12 rounds)
- JWT tokens (access: 15min, refresh: 7 days)
- Helmet.js for security headers
- CORS configured
- Rate limiting enabled
- Input validation with class-validator
- SQL injection prevention (TypeORM)
- XSS protection

## 📊 Logging

Using Pino logger with structured JSON logs.

**Log levels**:
- Development: `debug`
- Production: `info`

**Pretty print** in development with `pino-pretty`.

## 🚢 Carrier Integrations

MVP supports these carriers:
- Maersk
- MSC
- CMA CGM
- Hapag-Lloyd
- ONE (Ocean Network Express)

Each connector implements `CarrierConnectorPort` with:
- Circuit breaker (5s timeout)
- Retry logic
- Rate limiting
- Error normalization

## 📖 Further Reading

- [CLAUDE.md](../../CLAUDE.md) - Complete architecture guidelines
- [TODO.md](../../TODO.md) - Development roadmap
- [SPRINT-0-FINAL.md](../../SPRINT-0-FINAL.md) - Sprint 0 completion

## 🤝 Contributing

1. Follow hexagonal architecture principles
2. Write tests (domain: 90%+, application: 80%+)
3. Use TypeScript strict mode
4. Format with Prettier
5. Lint with ESLint
6. Document API with Swagger decorators

## 📝 License

Proprietary - All rights reserved

---

Built with ❤️ using NestJS and Hexagonal Architecture