xpeditis2.0/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Xpeditis is a B2B SaaS maritime freight booking and management platform (maritime equivalent of WebCargo). The platform allows freight forwarders to search and compare real-time shipping rates, book containers online, and manage shipments from a centralized dashboard.

Current Status: Phase 4 - Production-ready with security hardening, monitoring, and comprehensive testing infrastructure.

Active Feature: Carrier Portal (Branch: feature_dashboard_transporteur) - Dedicated portal for carriers to manage booking requests, view statistics, and download documents.

Development Commands

Local Development Setup

# Install all dependencies (monorepo)
npm install
cd apps/backend && npm install
cd ../frontend && npm install

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

# Verify all services are running
docker-compose ps
# Expected: xpeditis-postgres, xpeditis-redis, xpeditis-minio

# Run database migrations
cd apps/backend
npm run migration:run

# Start backend development server (with hot reload)
npm run backend:dev          # From root, or:
cd apps/backend && npm run dev

# Start frontend development server
npm run frontend:dev         # From root, or:
cd apps/frontend && npm run dev

Access Points:

• Frontend: http://localhost:3000
• Backend API: http://localhost:4000
• API Docs (Swagger): http://localhost:4000/api/docs
• MinIO Console (local S3): http://localhost:9001 (minioadmin/minioadmin)
• Carrier Portal: http://localhost:3000/carrier (in development)

Monorepo Scripts (from root)

# Development
npm run backend:dev          # Start backend dev server
npm run frontend:dev         # Start frontend dev server

# Testing
npm run backend:test         # Run backend unit tests
npm run frontend:test        # Run frontend tests
npm run backend:lint         # Lint backend code
npm run frontend:lint        # Lint frontend code

# Code Quality
npm run format               # Format all code (Prettier)
npm run format:check         # Check formatting

# Build
npm run backend:build        # Build backend for production
npm run frontend:build       # Build frontend for production

# Utilities
npm run install:all          # Install deps for all workspaces
npm run clean                # Clean all node_modules and build artifacts

Testing Commands

Backend Tests

cd apps/backend

# Unit tests (domain layer - no external dependencies)
npm test                          # Run all unit tests
npm run test:watch                # Run in watch mode
npm run test:cov                  # With coverage report

# Integration tests (infrastructure layer with real DB/Redis)
npm run test:integration          # Run all integration tests
npm run test:integration:watch    # Run in watch mode
npm run test:integration:cov      # With coverage report

# E2E tests (full API workflow)
npm run test:e2e                  # Run end-to-end tests

# Run a single test file
npm test -- booking.service.spec.ts
npm run test:integration -- redis-cache.adapter.spec.ts
npm run test:e2e -- carrier-portal.e2e-spec.ts

Load Testing (K6)

cd apps/backend

# Install k6 (macOS)
brew install k6

# Run rate search load test (100 virtual users)
k6 run load-tests/rate-search.test.js

# Run with custom parameters
k6 run --vus 50 --duration 60s load-tests/rate-search.test.js

E2E Testing (Playwright)

cd apps/frontend

# Install Playwright
npx playwright install

# Run E2E tests (booking workflow)
npx playwright test e2e/booking-workflow.spec.ts

# Run with UI mode
npx playwright test --ui

# Run specific browser
npx playwright test --project=chromium

API Testing (Postman/Newman)

# Install Newman globally
npm install -g newman

# Run Postman collection
newman run postman/Xpeditis_API.postman_collection.json

Database Migrations

cd apps/backend

# Generate new migration (after changing ORM entities)
npm run migration:generate -- src/infrastructure/persistence/typeorm/migrations/MigrationName

# Run pending migrations
npm run migration:run

# Revert last migration
npm run migration:revert

Build & Production

# Backend build
cd apps/backend
npm run build
npm run start:prod

# Frontend build
cd apps/frontend
npm run build
npm start

Architecture

Hexagonal Architecture (Ports & Adapters)

The backend follows strict hexagonal architecture with three isolated layers:

apps/backend/src/
├── application/        # 🔌 Controllers & DTOs (depends ONLY on domain)
│   ├── auth/          # JWT authentication module
│   ├── rates/         # Rate search endpoints
│   ├── bookings/      # Booking management
│   ├── csv-bookings.module.ts  # CSV booking imports
│   ├── modules/
│   │   └── carrier-portal.module.ts  # Carrier portal feature
│   ├── controllers/   # REST endpoints
│   │   ├── carrier-auth.controller.ts
│   │   └── carrier-dashboard.controller.ts
│   ├── dto/           # Data transfer objects with validation
│   │   └── carrier-auth.dto.ts
│   ├── services/      # Application services
│   │   ├── carrier-auth.service.ts
│   │   └── carrier-dashboard.service.ts
│   ├── guards/        # Auth guards, rate limiting, RBAC
│   └── mappers/       # DTO ↔ Domain entity mapping
│
└── infrastructure/    # 🏗️ External integrations (depends ONLY on domain)
    ├── persistence/typeorm/  # PostgreSQL repositories
    │   ├── entities/
    │   │   ├── carrier-profile.orm-entity.ts
    │   │   ├── carrier-activity.orm-entity.ts
    │   │   ├── csv-booking.orm-entity.ts
    │   │   └── organization.orm-entity.ts
    │   ├── repositories/
    │   │   ├── carrier-profile.repository.ts
    │   │   └── carrier-activity.repository.ts
    │   └── migrations/
    │       ├── 1733185000000-CreateCarrierProfiles.ts
    │       ├── 1733186000000-CreateCarrierActivities.ts
    │       ├── 1733187000000-AddCarrierToCsvBookings.ts
    │       └── 1733188000000-AddCarrierFlagToOrganizations.ts
    ├── cache/         # Redis adapter
    ├── carriers/      # Maersk, MSC, CMA CGM connectors
    │   └── csv-loader/  # CSV-based rate connector
    ├── email/         # MJML email service (carrier notifications)
    ├── storage/       # S3 storage adapter
    ├── websocket/     # Real-time carrier updates
    └── security/      # Helmet.js, rate limiting, CORS

Critical Rules:

1. Domain layer: No imports of NestJS, TypeORM, Redis, or any framework (domain layer not shown - pure business logic)
2. Dependencies flow inward: Infrastructure → Application → Domain
3. TypeScript path aliases: Use @domain/*, @application/*, @infrastructure/*
4. Testing: Domain tests must run without NestJS TestingModule

Frontend Architecture (Next.js 14 App Router)

apps/frontend/
├── app/                # Next.js 14 App Router (routing)
│   ├── page.tsx       # Landing page
│   ├── layout.tsx     # Root layout
│   ├── login/         # Auth pages
│   ├── register/
│   ├── dashboard/     # Protected dashboard routes
│   └── carrier/       # 🚛 Carrier portal routes (in development)
│       ├── login/
│       ├── dashboard/
│       └── bookings/
├── src/
│   ├── components/    # React components
│   │   ├── ui/       # shadcn/ui components (Button, Dialog, etc.)
│   │   ├── bookings/ # Booking components
│   │   └── admin/    # Admin components
│   ├── hooks/        # Custom React hooks
│   │   ├── useBookings.ts
│   │   ├── useCompanies.ts
│   │   └── useNotifications.ts
│   ├── lib/          # Utilities and API client
│   │   ├── api/      # API client modules
│   │   │   ├── auth.ts
│   │   │   ├── bookings.ts
│   │   │   ├── csv-rates.ts
│   │   │   └── dashboard.ts
│   │   ├── context/  # React contexts
│   │   └── providers/ # React Query and other providers
│   ├── types/        # TypeScript type definitions
│   │   ├── booking.ts
│   │   ├── carrier.ts
│   │   └── rates.ts
│   ├── utils/        # Helper functions
│   │   └── export.ts  # Excel/CSV/PDF export utilities
│   └── pages/        # Legacy page components
└── public/           # Static assets (logos, images)

Frontend Patterns:

• Server Components by default, Client Components when needed ("use client")
• React Hook Form + Zod for form validation
• TanStack Query for server state management
• Zustand for client state management
• shadcn/ui for accessible UI components

TypeScript Path Aliases (Frontend):

• @/* - Maps to ./src/*
• @/components/* - Maps to ./src/components/*
• @/lib/* - Maps to ./src/lib/*
• @/app/* - Maps to ./app/*
• @/types/* - Maps to ./src/types/*
• @/hooks/* - Maps to ./src/hooks/*
• @/utils/* - Maps to ./src/utils/*
• @/pages/* - Maps to ./src/pages/*

Tech Stack

Backend:

• NestJS 10+ (framework)
• TypeScript 5+ (strict mode)
• PostgreSQL 15+ (database)
• TypeORM 0.3+ (ORM)
• Redis 7+ (cache, 15min TTL for rates)
• Passport + JWT (authentication)
• Argon2 (password hashing)
• Helmet.js (security headers)
• Pino (structured logging)
• Sentry (error tracking + APM)

Frontend:

• Next.js 14+ App Router
• TypeScript 5+
• React 18+
• TanStack Table (data grids)
• TanStack Query (server state)
• React Hook Form + Zod (forms)
• Socket.IO (real-time updates)
• Tailwind CSS + shadcn/ui
• Framer Motion (animations)

Infrastructure:

• Docker + Docker Compose
• GitHub Actions (CI/CD)
• AWS RDS (PostgreSQL)
• AWS ElastiCache (Redis)
• AWS S3 (document storage)
• MinIO (local S3-compatible storage for development)

Testing Strategy

Test Coverage Targets

• Domain layer: 90%+ (currently ~100% for value objects and entities)
• Application layer: 80%+
• Infrastructure layer: 70%+ (currently ~82% for Phase 3 services)

Test File Locations

apps/backend/
├── src/
│   ├── application/
│   │   └── services/
│   │       ├── carrier-auth.service.spec.ts
│   │       └── carrier-dashboard.service.spec.ts
│   └── domain/
│       ├── entities/
│       │   └── rate-quote.entity.spec.ts
│       └── value-objects/
│           ├── email.vo.spec.ts
│           └── money.vo.spec.ts
├── test/
│   ├── integration/
│   │   ├── booking.repository.spec.ts
│   │   ├── redis-cache.adapter.spec.ts
│   │   └── maersk.connector.spec.ts
│   ├── carrier-portal.e2e-spec.ts     # Carrier portal E2E tests
│   ├── app.e2e-spec.ts
│   ├── jest-integration.json
│   ├── jest-e2e.json
│   └── setup-integration.ts
└── load-tests/
    └── rate-search.test.js

apps/frontend/
└── e2e/
    └── booking-workflow.spec.ts

Running Tests in CI

Tests run automatically on GitHub Actions for all PRs:

• Linting & formatting check
• Backend unit tests
• Backend integration tests (with PostgreSQL + Redis services)
• Backend E2E tests
• Frontend tests
• Security scans

See .github/workflows/ci.yml for full pipeline.

Security Features (Phase 4)

OWASP Top 10 Compliance:

• ✅ Helmet.js security headers (CSP, HSTS, X-Frame-Options)
• ✅ Rate limiting (global: 100/min, auth: 5/min, search: 30/min)
• ✅ Brute-force protection (exponential backoff after 3 failed attempts)
• ✅ File upload validation (MIME, magic number, size limits)
• ✅ Password policy (12+ chars, complexity requirements, Argon2 hashing)
• ✅ CORS with strict origin validation
• ✅ SQL injection prevention (TypeORM parameterized queries)
• ✅ XSS protection (CSP headers + input sanitization)

Monitoring & Observability:

• Sentry error tracking + APM (10% trace sampling)
• Performance monitoring interceptor (slow request alerts)
• Structured JSON logging with Pino
• WebSocket real-time notifications (NotificationsGateway)
• WebSocket carrier status updates

Database Schema

Key Tables:

• organizations - Freight forwarders and carriers (has is_carrier flag)
• users - User accounts with RBAC roles (Argon2 password hashing)
• carriers - Shipping line integrations (Maersk, MSC, CMA CGM, etc.)
• carrier_profiles - Carrier profile metadata and settings
• carrier_activities - Audit trail for carrier actions (accept/reject bookings, etc.)
• ports - 10k+ global ports (UN LOCODE)
• rate_quotes - Cached shipping rates (15min TTL)
• bookings - Container bookings (status workflow)
• containers - Container details (type, VGM, seal numbers)
• shipments - Real-time shipment tracking
• audit_logs - Compliance audit trail
• csv_rates - CSV-based rate data for offline/bulk rate loading
• csv_bookings - CSV-based booking imports (has carrier_id foreign key)
• notifications - User notifications (email, in-app)
• webhooks - Webhook configurations for external integrations

Migrations: Located in apps/backend/src/infrastructure/persistence/typeorm/migrations/

See apps/backend/DATABASE-SCHEMA.md for complete schema documentation.

Environment Variables

Required Variables

Backend (apps/backend/.env):

NODE_ENV=development
PORT=4000
DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_USER=xpeditis
DATABASE_PASSWORD=xpeditis_dev_password
DATABASE_NAME=xpeditis_dev
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=xpeditis_redis_password
JWT_SECRET=your-super-secret-jwt-key-change-this-in-production
JWT_ACCESS_EXPIRATION=15m
JWT_REFRESH_EXPIRATION=7d

# Email configuration (for carrier notifications)
EMAIL_HOST=smtp.example.com
EMAIL_PORT=587
EMAIL_USER=noreply@xpeditis.com
EMAIL_PASSWORD=your-email-password
EMAIL_FROM=noreply@xpeditis.com

Frontend (apps/frontend/.env.local):

NEXT_PUBLIC_API_URL=http://localhost:4000
NEXT_PUBLIC_WS_URL=ws://localhost:4000

See apps/backend/.env.example and apps/frontend/.env.example for all available variables.

API Documentation

OpenAPI/Swagger: http://localhost:4000/api/docs (when backend running)

Key Endpoints:

Client Portal

• POST /api/v1/auth/login - JWT authentication
• POST /api/v1/auth/register - User registration
• POST /api/v1/rates/search - Search shipping rates (cached 15min)
• POST /api/v1/rates/csv-search - Search rates from CSV data
• POST /api/v1/bookings - Create booking
• GET /api/v1/bookings - List bookings (paginated)
• GET /api/v1/bookings/:id - Get booking details
• POST /api/v1/bookings/csv-import - Bulk import bookings from CSV

Carrier Portal (New)

• POST /api/v1/carrier/auth/auto-login - Auto-login via magic link token
• POST /api/v1/carrier/auth/login - Standard carrier login
• GET /api/v1/carrier/dashboard/stats - Carrier dashboard statistics
• GET /api/v1/carrier/bookings - List bookings assigned to carrier
• GET /api/v1/carrier/bookings/:id - Get booking details
• PATCH /api/v1/carrier/bookings/:id/accept - Accept booking request
• PATCH /api/v1/carrier/bookings/:id/reject - Reject booking request
• GET /api/v1/carrier/profile - Get carrier profile
• PATCH /api/v1/carrier/profile - Update carrier profile

Common

• GET /api/v1/carriers/:id/status - Real-time carrier status
• GET /api/v1/notifications - Get user notifications
• WS /notifications - WebSocket for real-time notifications
• WS /carrier-status - WebSocket for carrier status updates

See apps/backend/docs/CARRIER_PORTAL_API.md for complete carrier portal API documentation.

Business Rules

Critical Constraints:

• Rate quotes expire after 15 minutes (Redis TTL)
• Carrier API timeout: 5 seconds per carrier
• Booking workflow: Maximum 4 steps
• Session timeout: 2 hours inactivity
• Rate search: <2s response time (90% with cache)
• Booking number format: WCM-YYYY-XXXXXX (6 alphanumeric chars)
• Cache hit target: >90% for common routes
• Multi-currency support: USD, EUR

RBAC Roles:

• ADMIN - Full system access
• MANAGER - Manage organization bookings + users
• USER - Create and view own bookings
• VIEWER - Read-only access
• CARRIER - Carrier portal access (view assigned bookings, accept/reject)

Carrier Portal Workflow:

1. Admin creates CSV booking and assigns carrier
2. Email sent to carrier with magic link (auto-login token, valid 1 hour)
3. Carrier clicks link → auto-login → redirected to dashboard
4. Carrier can accept/reject booking, download documents
5. Activity logged in carrier_activities table
6. Client notified of carrier decision

Real-Time Features (WebSocket)

The platform uses WebSocket connections for real-time updates:

Notifications Gateway (application/gateways/notifications.gateway.ts):

• Real-time user notifications (booking updates, system alerts)
• JWT-authenticated WebSocket connections
• Auto-reconnect with exponential backoff
• Connect to ws://localhost:4000/notifications

Carrier Status Updates:

• Real-time carrier API status monitoring
• Live shipment tracking updates
• Connection status: online/offline/degraded
• Connect to ws://localhost:4000/carrier-status

Frontend Integration:

• Socket.IO client for WebSocket connections
• Context providers in lib/providers/
• Real-time notification dropdown component
• Auto-refresh on status changes

CSV Import/Export Features

The platform supports CSV-based operations for bulk data management:

CSV Rate Search:

• Upload CSV files with rate data for offline/bulk rate loading
• CSV-based carrier connectors in infrastructure/carriers/csv-loader/
• Stored in csv_rates table
• Accessible via admin dashboard at /admin/csv-rates

CSV Booking Import:

• Bulk import bookings from CSV files
• Validation and mapping to domain entities
• Stored in csv_bookings table
• CSV parsing with csv-parse library
• Automatic carrier assignment and email notification

Export Features:

• Export bookings to Excel (.xlsx) using exceljs
• Export to CSV format
• Export to PDF documents using pdfkit
• File downloads using file-saver on frontend

Admin User Management

The platform includes a dedicated admin interface for user management:

Admin Features (Branch: users_admin):

• User CRUD operations (Create, Read, Update, Delete)
• Organization management
• Role assignment and permissions
• Argon2 password hash generation for new users
• Accessible at /admin/users (ADMIN role required)

Password Hashing Utility:

• Use apps/backend/generate-hash.js to generate Argon2 password hashes
• Example: node apps/backend/generate-hash.js mypassword

Deployment

Docker Build

# Build backend image
docker build -t xpeditis-backend:latest -f apps/backend/Dockerfile .

# Build frontend image
docker build -t xpeditis-frontend:latest -f apps/frontend/Dockerfile .

# Run with Docker Compose (development)
docker-compose up -d

Production Deployment (Portainer)

See docker/PORTAINER_DEPLOYMENT_GUIDE.md for complete instructions:

• Scaleway Container Registry (rg.fr-par.scw.cloud/weworkstudio)
• Docker Swarm stack deployment
• Traefik reverse proxy configuration
• Environment-specific configs (staging/production)

CI/CD: Automated via GitHub Actions

• Build and push Docker images to Scaleway Registry
• Deploy to staging/production via Portainer
• Run smoke tests post-deployment

Deployment Scripts:

• docker/build-images.sh - Build and tag Docker images
• deploy-to-portainer.sh - Automated deployment script
• docker/portainer-stack.yml - Production stack configuration

Performance Targets

• Rate search: <2s for 90% of requests (with cache)
• Rate search: <5s for 90% of requests (cache miss)
• Dashboard load: <1s for up to 5k bookings
• Email confirmation: Send within 3s of booking
• Carrier email notification: Send within 5s of booking assignment
• Cache hit ratio: >90% for top 100 trade lanes
• Carrier API timeout: 5s (with circuit breaker)

Naming Conventions

TypeScript:

• Entities: Booking, RateQuote, CarrierProfile (PascalCase)
• Value Objects: Email, Money, BookingNumber
• Services: BookingService, RateSearchService, CarrierAuthService
• Repositories: BookingRepository, CarrierProfileRepository (interface in domain)
• Repository Implementations: TypeOrmBookingRepository, TypeOrmCarrierProfileRepository
• DTOs: CreateBookingDto, RateSearchRequestDto, CarrierAutoLoginDto
• Ports: SearchRatesPort, CarrierConnectorPort

Files:

• Entities: booking.entity.ts
• Value Objects: email.vo.ts
• Services: booking.service.ts, carrier-auth.service.ts
• Tests: booking.service.spec.ts, carrier-auth.service.spec.ts
• ORM Entities: booking.orm-entity.ts, carrier-profile.orm-entity.ts
• Migrations: 1730000000001-CreateBookings.ts, 1733185000000-CreateCarrierProfiles.ts

Common Pitfalls to Avoid

❌ DO NOT:

• Import NestJS/TypeORM in domain layer
• Put business logic in controllers or repositories
• Use any type (strict mode enabled)
• Skip writing tests (coverage targets enforced)
• Use DATABASE_SYNC=true in production
• Commit .env files
• Expose sensitive data in API responses
• Skip rate limiting on public endpoints
• Use circular imports (leverage barrel exports)
• Send emails without proper error handling
• Store plain text passwords (always use Argon2)

✅ DO:

• Follow hexagonal architecture strictly
• Write tests for all new features (domain 90%+)
• Use TypeScript path aliases (@domain/*, @application/*, @infrastructure/*)
• Validate all DTOs with class-validator
• Implement circuit breakers for external APIs
• Cache frequently accessed data (Redis)
• Use structured logging (Pino)
• Document APIs with Swagger decorators
• Run migrations before deployment
• Test email sending in development with test accounts
• Use MJML for responsive email templates

Documentation

Architecture & Planning:

• ARCHITECTURE.md - System architecture (5,800 words)
• DEPLOYMENT.md - Deployment guide (4,500 words)
• PRD.md - Product requirements
• TODO.md - 30-week development roadmap
• CARRIER_PORTAL_IMPLEMENTATION_PLAN.md - Carrier portal implementation plan

Implementation Summaries:

• PHASE4_SUMMARY.md - Security, monitoring, testing
• PHASE3_COMPLETE.md - Booking workflow, exports
• PHASE2_COMPLETE.md - Authentication, RBAC
• PHASE-1-WEEK5-COMPLETE.md - Rate search, cache

API Documentation:

• apps/backend/docs/CARRIER_PORTAL_API.md - Carrier portal API reference

Testing:

• TEST_EXECUTION_GUIDE.md - How to run all tests
• TEST_COVERAGE_REPORT.md - Coverage metrics
• GUIDE_TESTS_POSTMAN.md - Postman API tests

Deployment:

• docker/PORTAINER_DEPLOYMENT_GUIDE.md - Portainer setup
• docker/DOCKER_BUILD_GUIDE.md - Docker build instructions
• DEPLOYMENT_CHECKLIST.md - Pre-deployment checklist

Code Review Checklist

1. Hexagonal architecture principles followed
2. Domain layer has zero external dependencies
3. Unit tests written (90%+ coverage for domain)
4. Integration tests for infrastructure adapters
5. DTOs validated with class-validator
6. Swagger documentation updated
7. No secrets committed
8. TypeScript strict mode passes
9. Prettier formatting applied
10. ESLint passes with no warnings
11. Email templates tested in development
12. Carrier workflow tested end-to-end