David/xpeditis2.0
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
591213aaf7
xpeditis2.0/CLAUDE.md
David a34c850e67 fix register
2025-11-29 12:50:02 +01:00

20 KiB
Raw Blame History

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.

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:

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

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/
├── domain/              # 🎯 Pure business logic (ZERO external dependencies)
│   ├── entities/       # Booking, RateQuote, User, Organization, Carrier
│   ├── value-objects/  # Email, Money, BookingNumber, PortCode
│   ├── services/       # Domain services (rate-search, booking, availability)
│   ├── ports/
│   │   ├── in/        # Use cases (search-rates, create-booking)
│   │   └── out/       # Repository interfaces, connector ports
│   └── exceptions/    # Business exceptions
│
├── application/        # 🔌 Controllers & DTOs (depends ONLY on domain)
│   ├── controllers/   # REST endpoints
│   ├── dto/           # Data transfer objects with validation
│   ├── guards/        # Auth guards, rate limiting, RBAC
│   ├── services/      # Brute-force protection, file validation
│   └── mappers/       # DTO ↔ Domain entity mapping
│
└── infrastructure/    # 🏗️ External integrations (depends ONLY on domain)
    ├── persistence/typeorm/  # PostgreSQL repositories
    ├── cache/               # Redis adapter
    ├── carriers/            # Maersk, MSC, CMA CGM connectors
    ├── email/               # MJML email service
    ├── 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
  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
├── src/
│   ├── components/    # React components
│   │   ├── ui/       # shadcn/ui components (Button, Dialog, etc.)
│   │   └── features/ # Feature-specific components
│   ├── hooks/        # Custom React hooks
│   ├── lib/          # Utilities and API client
│   ├── types/        # TypeScript type definitions
│   ├── utils/        # Helper functions
│   └── 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/
│   └── domain/
│       ├── entities/
│       │   └── rate-quote.entity.spec.ts        # Unit test example
│       └── value-objects/
│           ├── email.vo.spec.ts
│           └── money.vo.spec.ts
├── test/
│   ├── integration/                              # Infrastructure tests
│   │   ├── booking.repository.spec.ts
│   │   ├── redis-cache.adapter.spec.ts
│   │   └── maersk.connector.spec.ts
│   ├── app.e2e-spec.ts                          # E2E API tests
│   ├── jest-integration.json                     # Integration test config
│   └── setup-integration.ts                      # Test setup
└── load-tests/
    └── rate-search.test.js                       # K6 load tests

apps/frontend/
└── e2e/
    └── booking-workflow.spec.ts                  # Playwright E2E tests

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
  • users - User accounts with RBAC roles (Argon2 password hashing)
  • carriers - Shipping line integrations (Maersk, MSC, CMA CGM, 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
  • 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

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:

  • 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/bookings - Create booking
  • GET /api/v1/bookings - List bookings (paginated)
  • GET /api/v1/bookings/:id - Get booking details
  • GET /api/v1/carriers/:id/status - Real-time carrier status
  • POST /api/v1/rates/csv-search - Search rates from CSV data
  • POST /api/v1/bookings/csv-import - Bulk import bookings from CSV
  • GET /api/v1/notifications - Get user notifications
  • WS /notifications - WebSocket for real-time notifications
  • WS /carrier-status - WebSocket for carrier status updates

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

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

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
  • Cache hit ratio: >90% for top 100 trade lanes
  • Carrier API timeout: 5s (with circuit breaker)

Naming Conventions

TypeScript:

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

Files:

  • Entities: booking.entity.ts
  • Value Objects: email.vo.ts
  • Services: booking.service.ts
  • Tests: booking.service.spec.ts
  • ORM Entities: booking.orm-entity.ts
  • Migrations: 1730000000001-CreateBookings.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)

✅ DO:

  • Follow hexagonal architecture strictly
  • Write tests for all new features (domain 90%+)
  • Use TypeScript path aliases (@domain/*)
  • 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

Documentation

Architecture & Planning:

Implementation Summaries:

Testing:

Deployment:

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