David/xpeditis2.0

Fork 0

David-Henri ARNAUD e863399bb2

CI / Lint & Format Check (push) Failing after 1m11s

Details

CI / Test Backend (push) Failing after 1m32s

Details

CI / Build Backend (push) Has been skipped

Details

Security Audit / npm audit (push) Failing after 5s

Details

Security Audit / Dependency Review (push) Has been skipped

Details

CI / Test Frontend (push) Failing after 29s

Details

CI / Build Frontend (push) Has been skipped

Details

first commit

2025-10-07 18:39:32 +02:00

40 KiB

Raw Blame History

TODO - Xpeditis MVP Implementation Roadmap

Project: Xpeditis - Maritime Freight Booking Platform (B2B SaaS) Timeline: 4-6 months Goal: 50-100 bookings/month for 10-20 early adopter freight forwarders

📅 SPRINT 0 - PROJECT SETUP & INFRASTRUCTURE (2 weeks)

Week 1: Repository & Development Environment

Initialize monorepo structure
- Create root directory with workspace configuration (npm/yarn/pnpm workspaces)
- Setup folder structure:
```
/apps/frontend
/apps/backend
/packages/shared-types
/packages/domain
/infra
```
- Initialize Git repository
- Create .gitignore (node_modules, .env, build artifacts)
Backend setup (Node.js + NestJS + TypeScript)
- Initialize NestJS project: nest new backend
- Configure TypeScript (strict: true, path aliases)
- Setup ESLint + Prettier
- Configure Husky pre-commit hooks
- Create hexagonal architecture folder structure:
  - /src/domain (entities, ports, services)
  - /src/application (controllers, DTOs)
  - /src/infrastructure (adapters, persistence)
- Setup .env.example with required variables
Frontend setup (Next.js 14+ TypeScript)
- Initialize Next.js project with App Router
- Configure TypeScript with strict mode
- Setup Tailwind CSS
- Install UI library (shadcn/ui or similar)
- Configure path aliases in tsconfig.json
- Setup ESLint + Prettier
Database setup
- Choose PostgreSQL version (15+)
- Setup local PostgreSQL via Docker
- Create Docker Compose file for dev environment
- Install TypeORM in backend
- Create initial database schema design document
- Setup database migrations folder
Redis cache setup
- Add Redis service to Docker Compose
- Install ioredis package
- Create Redis configuration module
- Test Redis connection

Week 2: CI/CD, Documentation & Core Infrastructure

Version control & collaboration
- Create GitHub repository (or GitLab/Bitbucket)
- Setup branch protection rules (main/develop)
- Create pull request template
- Setup GitHub Actions workflows (or equivalent CI)
CI/CD pipelines
- Workflow: Lint & format check
- Workflow: Run unit tests
- Workflow: Build backend
- Workflow: Build frontend
- Workflow: Run integration tests
- Setup environment secrets
API documentation
- Install @nestjs/swagger
- Configure Swagger UI endpoint (/api/docs)
- Create OpenAPI base configuration
- Document authentication endpoints
Monitoring & logging setup
- Install Winston or Pino for logging
- Configure log levels (dev/staging/prod)
- Setup error tracking (Sentry or similar)
- Create logging middleware
Security foundations
- Install helmet.js for security headers
- Configure CORS properly
- Setup rate limiting (express-rate-limit)
- Configure CSP headers
- Create security checklist document
Testing infrastructure
- Configure Jest for backend
- Setup test database (SQLite in-memory or testcontainers)
- Install Supertest for API testing
- Configure Jest for frontend (React Testing Library)
- Install @faker-js/faker for test data
- Create test utilities and factories

📅 PHASE 1 - CORE SEARCH & CARRIER INTEGRATION (6-8 weeks)

Sprint 1-2: Domain Layer & Port Definitions (2 weeks)

Week 3: Domain Entities & Value Objects

Create core domain entities
- Organization entity
  - Properties: id, name, type, scac, address, logo_url, documents[]
  - Business rules: unique SCAC validation
- User entity
  - Properties: id, org_id, role, email, pwd_hash, totp_secret
  - Business rules: email validation, password complexity
- RateQuote entity
  - Properties: id, origin, destination, carrier_id, price, surcharges[], etd, eta, transit_days, route[], availability
  - Business rules: price validation, date consistency
- Carrier entity
  - Properties: id, name, code, logo_url, api_config
- Port entity
  - Properties: code, name, country, coordinates
- Container entity (basic)
  - Properties: id, type, size, category (DRY/REEFER)
Create Value Objects
- Email value object (validation)
- PortCode value object (UN LOCODE format)
- Money value object (currency + amount)
- ContainerType value object (20'DRY, 40'HC, etc.)
- DateRange value object (ETD/ETA validation)
Create domain exceptions
- InvalidPortCodeException
- InvalidRateQuoteException
- CarrierTimeoutException
- RateQuoteExpiredException

Week 4: Ports & Domain Services

Define API Ports (domain/ports/in/)
- SearchRatesPort interface
```
interface SearchRatesPort {
  execute(input: RateSearchInput): Promise<RateQuote[]>;
}
```
- GetPortsPort interface (autocomplete)
- ValidateAvailabilityPort interface

Define SPI Ports (domain/ports/out/)

RateQuoteRepository interface
PortRepository interface
CarrierRepository interface

CarrierConnectorPort interface

interface CarrierConnectorPort {
  searchRates(input: RateSearchInput): Promise<RateQuote[]>;
  checkAvailability(input: AvailabilityInput): Promise<boolean>;
}

CachePort interface

interface CachePort {
  get<T>(key: string): Promise<T | null>;
  set<T>(key: string, value: T, ttl: number): Promise<void>;
}

Implement domain services
- RateSearchService (implements SearchRatesPort)
  - Cache checking logic
  - Parallel carrier querying with Promise.allSettled
  - Result aggregation and normalization
  - Cache storage (15 min TTL)
- PortSearchService
  - Fuzzy search implementation
  - Autocomplete logic (top 10 results)
Write domain unit tests
- Test RateSearchService with mocked dependencies
- Test Value Object validations
- Test domain exception scenarios
- Target: 90%+ coverage on domain layer

Sprint 3-4: Infrastructure Layer - Persistence & Cache (2 weeks)

Week 5: Database & Repositories

Design database schema
- Create ERD diagram (organizations, users, carriers, ports, rate_quotes)
- Define relationships and indexes
- Document migration strategy
Create TypeORM entities (infrastructure/persistence/typeorm/entities/)
- OrganizationOrmEntity
- UserOrmEntity
- CarrierOrmEntity
- PortOrmEntity
- RateQuoteOrmEntity
Implement ORM mappers
- OrganizationOrmMapper (ORM ↔ Domain)
- UserOrmMapper
- CarrierOrmMapper
- PortOrmMapper
- RateQuoteOrmMapper
Implement repositories
- TypeOrmRateQuoteRepository (implements RateQuoteRepository port)
- TypeOrmPortRepository
- TypeOrmCarrierRepository
- Add proper error handling
- Add query optimization (indexes, eager/lazy loading)
Database migrations
- Migration: Create organizations table
- Migration: Create users table
- Migration: Create carriers table
- Migration: Create ports table (seed with 10k+ ports)
- Migration: Create rate_quotes table
- Migration: Add indexes for search optimization
Seed data
- Seed major carriers (Maersk, MSC, CMA CGM, Hapag-Lloyd, ONE)
- Seed world ports database (UN LOCODE dataset)
- Seed test organizations
- Create seeding scripts

Week 6: Redis Cache & Carrier Connectors Foundation

Implement Redis cache adapter
- RedisCacheAdapter (implements CachePort)
- Implement get/set with TTL
- Implement cache key generation strategy
- Add connection error handling
- Add cache metrics (hit/miss rate)
Create carrier connector base structure
- BaseCarrierConnector abstract class
  - HTTP client setup (axios with timeout)
  - Retry logic (exponential backoff)
  - Circuit breaker pattern (using opossum)
  - Request/response logging
  - Error normalization
- CarrierConnectorFactory (Strategy pattern)
Implement Maersk connector (Priority 1)
- Research Maersk API documentation
- Obtain API credentials (sandbox)
- MaerskConnectorAdapter implementing CarrierConnectorPort
- MaerskRequestMapper (internal format → Maersk API format)
- MaerskResponseMapper (Maersk API → domain RateQuote)
- Handle Maersk-specific error codes
- Add 5s timeout
- Unit tests with mocked responses
Integration tests
- Test repository CRUD operations with test database
- Test Redis cache adapter
- Test Maersk connector with sandbox API
- Target: 70%+ coverage on infrastructure layer

Sprint 5-6: Application Layer & Rate Search API (2 weeks)

Week 7: DTOs, Mappers & Controllers

Create DTOs (application/dto/)

RateSearchRequestDto

{
  origin: string;           // Port code
  destination: string;
  containerType: string;    // '20DRY', '40HC', etc.
  mode: 'FCL' | 'LCL';
  departureDate: string;    // ISO 8601
  weight?: number;          // For LCL
  volume?: number;          // For LCL
  hazmat: boolean;
  imoClass?: string;
}

RateQuoteResponseDto

{
  id: string;
  carrier: { name, logo };
  origin: { code, name };
  destination: { code, name };
  price: { amount, currency };
  surcharges: Array<{ type, amount }>;
  transitDays: number;
  etd: string;
  eta: string;
  route: Array<{ port, arrival, departure }>;
  availability: number;
  frequency: string;
  vesselType: string;
  co2Kg: number;
}

PortAutocompleteDto
Add class-validator decorators to all DTOs

Create application mappers
- RateSearchMapper (DTO ↔ Domain)
- PortMapper
- Ensure proper type safety
Implement validation pipes
- Custom validation pipe for port codes
- Custom validation pipe for container types
- Custom validation pipe for dates (future dates only)
Create controllers
- RatesController
  - POST /api/v1/rates/search endpoint
  - Input validation
  - Error handling with proper HTTP status codes
  - Response transformation
- PortsController
  - GET /api/v1/ports/autocomplete?q={query} endpoint
  - Query parameter validation
  - Response pagination

Week 8: API Documentation, Testing & Optimization

Complete OpenAPI documentation
- Document POST /api/v1/rates/search
  - Request body schema
  - Response schema
  - Error responses (400, 404, 500, 503)
  - Example requests/responses
- Document GET /api/v1/ports/autocomplete
- Add API authentication documentation (for later)
Implement caching strategy
- Cache top 100 trade lanes on application startup
- Implement background job for cache warming
- Add cache invalidation logic
- Monitor cache hit ratio
Performance optimization
- Add database query optimization (explain analyze)
- Implement parallel carrier API calls
- Add request timeout handling
- Optimize port autocomplete with database indexes
API tests
- E2E test: Search rates happy path
- E2E test: Search with invalid port code (400)
- E2E test: Search with all carriers timeout (503)
- E2E test: Port autocomplete
- Load testing with k6 or Artillery (target: <2s response time)
Error handling & logging
- Implement global exception filter
- Add request/response logging middleware
- Add correlation IDs to logs
- Setup log aggregation (structured JSON logs)

Sprint 7-8: Frontend Rate Search UI (2 weeks)

Setup frontend architecture
- Create folder structure:
```
/app/(routes)/search/
/components/search/
/lib/api/
/lib/hooks/
/lib/types/
```
- Configure API client (axios or fetch wrapper)
- Setup environment variables
Create search form components
- SearchForm component
- PortAutocomplete component
  - Debounced search (300ms)
  - Loading states
  - Keyboard navigation (arrow keys, enter)
- DatePicker component (with availability calendar)
- ContainerTypeSelector component (radio buttons or dropdown)
- ModeSelector component (FCL/LCL toggle)
- HazmatInput component (checkbox + IMO class conditional input)
- WeightVolumeInput component (for LCL mode)
Form validation
- Install zod or yup for schema validation
- Create validation schema matching backend DTOs
- Real-time validation feedback
- Error message display
State management
- Setup React Query (TanStack Query) for API calls
- Create useSearchRates hook
- Create usePortAutocomplete hook
- Implement loading, error, and success states
- Add optimistic updates

Week 10: Results Display & Filtering

Create results components
- RateQuoteCard component
  - Carrier logo and name
  - Origin → Destination with route visualization
  - Price breakdown (all-in + surcharges tooltip)
  - Transit time badge
  - ETD/ETA display
  - Availability indicator
  - CO2 emissions badge
  - "Book Now" button
- RateQuoteTable component (alternative view)
  - Sortable columns
  - Responsive design
Filtering & sorting UI
- FilterPanel component
  - Price range slider
  - Transit time range
  - Carrier selection (checkboxes)
  - CO2 filter
- SortDropdown component
  - Sort by: Price (low/high), Transit time, CO2
- Implement client-side filtering and sorting
Results enhancements
- Pagination component (if >20 results)
- View toggle (cards vs table)
- Export functionality (PDF/Excel)
  - Install jsPDF or similar
  - Create export templates
- Empty state component (no results found)
- Loading skeleton components
Responsive design
- Mobile-first layout
- Tablet breakpoint adjustments
- Desktop optimization
- Touch-friendly interactions
Frontend testing
- Unit tests for components (React Testing Library)
- Integration tests for search flow
- E2E tests with Playwright or Cypress
- Accessibility testing (axe-core)

📅 PHASE 2 - BOOKING & USER MANAGEMENT (6-8 weeks)

Sprint 9-10: Authentication System (2 weeks)

Week 11: Backend Authentication

JWT authentication setup
- Install @nestjs/jwt and @nestjs/passport
- Create JWT strategy
- Configure JWT tokens:
  - Access token: 15 minutes expiry
  - Refresh token: 7 days expiry
- Create auth guard
- Implement token refresh mechanism
User domain & repositories
- Create User domain entity (if not done)
- Create UserOrmEntity
- Implement UserRepository
- Add password hashing (bcrypt with 12 rounds)
Auth endpoints
- POST /auth/register
  - Email validation
  - Password complexity check (min 12 chars)
  - Create user in database
  - Send verification email
- POST /auth/login
  - Credential validation
  - Return JWT tokens
  - Log login event
- POST /auth/refresh
  - Validate refresh token
  - Issue new access token
- POST /auth/logout
  - Invalidate refresh token
- POST /auth/forgot-password
  - Generate reset token
  - Send reset email
- POST /auth/reset-password
  - Validate reset token
  - Update password
Email verification
- Generate verification tokens
- GET /auth/verify-email?token=xxx
- Email template for verification
- Resend verification email endpoint
OAuth2 integration
- Google OAuth2 strategy
  - Install passport-google-oauth20
  - Configure Google Cloud Console
  - Implement callback handler
- Microsoft OAuth2 strategy
  - Install passport-microsoft
  - Configure Azure AD
  - Implement callback handler
2FA (TOTP) - Optional
- Install speakeasy for TOTP
- POST /auth/2fa/setup (generate secret)
- POST /auth/2fa/verify (verify code)
- POST /auth/2fa/disable
Security measures
- Implement rate limiting on auth endpoints
- Add account lockout after failed attempts
- Store hashed passwords (Argon2id or bcrypt)
- Implement CSRF protection
- Add session management (auto logout after 2h inactivity)

Week 12: Organization & RBAC

Organization management
- Create Organization domain entity (if not done)
- Create OrganizationOrmEntity
- Implement OrganizationRepository
- POST /organizations - Create organization
- GET /organizations/:id - Get organization
- PATCH /organizations/:id - Update organization
- POST /organizations/:id/logo - Upload logo (S3)
RBAC implementation
- Define roles enum: Admin, Manager, User, Viewer
- Create permission decorators
```
@Roles('Admin', 'Manager')
@RequirePermission('bookings:create')
```
- Implement RBAC guard
- Add role-based access to all protected routes
User management endpoints
- GET /organizations/:id/users - List users
- POST /organizations/:id/users - Invite user
- PATCH /users/:id - Update user
- DELETE /users/:id - Remove user
- PATCH /users/:id/role - Change user role
Onboarding flow
- Create multi-step onboarding API
- Store onboarding progress
- POST /onboarding/complete

Sprint 11-12: Frontend Authentication (2 weeks)

Week 13: Auth UI Components

Setup frontend auth
- Install next-auth or custom auth context
- Create auth API routes (/api/auth/*)
- Setup secure cookie handling
- Implement token refresh logic
Auth pages
- /login page
  - Email/password form
  - OAuth buttons (Google, Microsoft)
  - "Forgot password" link
  - Form validation
- /register page
  - Multi-step registration form
  - Email/password fields
  - Password strength indicator
  - Terms & Conditions checkbox
- /forgot-password page
- /reset-password page
- /verify-email page
Protected routes
- Create auth middleware for Next.js
- Redirect unauthenticated users
- Implement role-based route protection
Auth components
- LoginForm component
- RegisterForm component
- OAuthButtons component
- PasswordInput component (with show/hide toggle)
- PasswordStrengthMeter component

Week 14: Organization & User Management UI

Organization settings page
- /settings/organization route
- Display organization details
- Edit organization form
- Logo upload component
- Document upload component
User management page
- /settings/users route
- User list table
- Invite user modal
- Edit user modal
- Role selector dropdown
- Remove user confirmation dialog
Onboarding flow UI
- /onboarding route
- Multi-step wizard component
- Progress indicator
- Step validation
- Final confirmation screen
User profile
- /profile page
- Edit profile form
- Change password form
- 2FA setup UI (if implemented)
- Session management (active sessions list)

Sprint 13-14: Booking Workflow Backend (2 weeks)

Week 15: Booking Domain & API

Booking domain entities

Booking entity

{
  id, bookingNumber, userId, orgId,
  rateQuoteId, shipper, consignee, notifyParty,
  containers[], cargoDetails, specialInstructions,
  status, createdAt, updatedAt
}

Container entity (detailed)

{
  id, bookingId, type, quantity, temperature,
  ventilation, vgm, sealNumber, containerNumber
}

BookingStatus enum (Pending, Confirmed, InTransit, Arrived, Cancelled)

Booking ports
- CreateBookingPort interface
- GetBookingPort interface
- UpdateBookingPort interface
- CancelBookingPort interface
- BookingRepository port
Booking service
- BookingService implementation
- Generate unique booking number (WCM-YYYY-XXXXXX format)
- Validate rate quote availability
- Business rules validation
- Create booking with all related entities
Booking infrastructure
- BookingOrmEntity
- ContainerOrmEntity
- TypeOrmBookingRepository
- Booking-Container relationship mapping
- Database migrations for booking tables
Booking API endpoints
- POST /api/v1/bookings - Create booking
  - Validate input (multi-step data)
  - Check rate quote availability
  - Create booking record
  - Return booking confirmation
- GET /api/v1/bookings/:id - Get booking details
- GET /api/v1/bookings - List bookings (with filters)
  - Query params: status, dateRange, carrier, route
  - Pagination
  - Sorting
- PATCH /api/v1/bookings/:id - Update booking
- DELETE /api/v1/bookings/:id - Cancel booking
- GET /api/v1/bookings/:id/documents - Get booking documents

Week 16: Email & Document Generation

Email service infrastructure
- Install nodemailer
- Configure email provider (SendGrid/AWS SES)
- Create EmailPort interface
- Implement EmailAdapter
- Email template engine setup (MJML + Handlebars)
Email templates
- Booking confirmation email
  - Professional HTML template
  - Include booking number, details, and PDF attachment
  - Responsive design
- Verification email template
- Password reset email template
- Welcome email template
PDF generation
- Install puppeteer or pdfkit
- Create booking confirmation PDF template
  - Header with logos
  - Booking details table
  - Terms & Conditions
  - QR code (optional)
- Implement PDF generation service
- GET /api/v1/bookings/:id/pdf endpoint
Document storage
- Setup S3 or MinIO
- Create StoragePort interface
- Implement S3StorageAdapter
- POST /api/v1/bookings/:id/documents - Upload document
- Document metadata storage in database
Post-booking automation
- Trigger email on booking creation
- Generate PDF automatically
- Store PDF in S3
- Create audit log entry
- Implement retry mechanism for failed emails

Sprint 15-16: Booking Workflow Frontend (2 weeks)

Week 17: Multi-Step Booking Form

Booking flow setup
- Create /booking route with query params for rate quote
- Setup multi-step form state management (Zustand or React Context)
- Create step navigation component
- Progress indicator UI
Step 1: Offer Selection & Verification
- Display selected rate quote summary
- Real-time availability check
- Price breakdown display
- "Continue" button with loading state
Step 2: Shipper/Consignee Information
- ShipperConsigneeForm component
- Address autocomplete (Google Maps API)
- Contact information fields
- Address book integration (saved contacts)
- "Same as shipper" checkbox for notify party
- Form validation
- Save to address book option
Step 3: Container & Cargo Details
- ContainerDetailsForm component
- Container quantity selector
- Container type dropdown
- Temperature input (conditional for reefer)
- Ventilation checkbox
- VGM input
- Seal number input
- Cargo description textarea
- HS Code input with autocomplete
- Cargo value input
- Special instructions textarea
- Document upload component (drag & drop)
Step 4: Review & Confirmation
- BookingSummary component
- Display all entered information
- Edit buttons for each section (go back to step)
- Terms & Conditions modal
- T&C acceptance checkbox
- "Confirm Booking" button
- Loading state during submission
- Error handling

Week 18: Booking Confirmation & Management

Booking confirmation page
- /booking/confirmation/:id route
- Success animation/illustration
- Display booking number prominently
- Show booking details
- Download PDF button
- "Go to Dashboard" button
- Email confirmation status
Booking detail page
- /bookings/:id route
- Full booking information display
- Status badge
- Timeline component (booking lifecycle)
  - Booking created
  - Confirmed by carrier
  - Container picked up
  - Departed origin port
  - In transit
  - Arrived destination port
- Document list (uploaded + generated)
- Download all documents (ZIP)
- Edit button (if status allows)
- Cancel button with confirmation dialog
- Internal notes section (comments)
Edit booking functionality
- /bookings/:id/edit route
- Pre-populate form with existing data
- Prevent editing of locked fields
- Show change summary before saving
- Update API call
- Audit log of changes
Cancel booking
- Confirmation dialog with reason textarea
- API call to cancel
- Update UI to show cancelled status
- Send cancellation email

📅 PHASE 3 - DASHBOARD & ADDITIONAL CARRIERS (4-6 weeks)

Sprint 17-18: Dashboard Backend & Analytics (2 weeks)

Week 19: Dashboard API & Analytics

Analytics service
- Create AnalyticsService
- Calculate KPIs:
  - Bookings this month
  - Total TEUs
  - Estimated revenue
  - Pending confirmations count
- Implement caching for analytics (1 hour TTL)
Dashboard endpoints
- GET /api/v1/dashboard/kpis - Get key metrics
- GET /api/v1/dashboard/bookings-chart - Bookings over time (6 months)
- GET /api/v1/dashboard/top-trade-lanes - Top 5 routes
- GET /api/v1/dashboard/alerts - Important notifications
Bookings list API enhancements
- Advanced filtering:
  - Status (multiple selection)
  - Date range (custom or presets)
  - Carrier
  - Origin/destination
  - Search by booking number
- Sorting on all columns
- Pagination (cursor-based or offset)
- GET /api/v1/bookings/export - Export to CSV/Excel
Search & filtering optimization
- Implement fuzzy search (PostgreSQL full-text search or ElasticSearch)
- Add database indexes for common queries
- Cache common filter combinations

Week 20: Audit Logs & Notifications

Audit logging
- Create AuditLog entity
- Implement audit logging middleware
- Log all booking changes
- Log user actions (login, role changes, etc.)
- GET /api/v1/bookings/:id/audit-log endpoint
Notification system
- Create Notification entity
- Implement notification service
- Notification types:
  - Booking confirmed
  - Booking delayed
  - Document uploaded
  - Payment required
- GET /api/v1/notifications endpoint
- PATCH /api/v1/notifications/:id/read - Mark as read
- Real-time notifications (WebSocket or Server-Sent Events)
Webhooks (optional)
- Webhook entity
- Webhook registration API
- Webhook delivery system
- Retry logic for failed webhooks

Sprint 19-20: Dashboard Frontend (2 weeks)

Week 21: Dashboard UI Components

Dashboard layout
- Create /dashboard route
- Sidebar navigation
- Top bar with user menu
- Responsive layout
KPI Cards
- KPICard component
- Bookings this month card (with trend indicator)
- Total TEUs card
- Estimated revenue card
- Pending confirmations card
- Loading skeletons
Charts
- Install Recharts or Chart.js
- BookingsLineChart component (6 months trend)
- TopTradeLanesChart component (bar chart)
- Chart responsive design
- Chart tooltips and legends
Alerts section
- AlertsList component
- Alert type icons (delay, confirmation, etc.)
- Clickable alerts (navigate to booking)
- Dismiss alert functionality

Week 22: Bookings List & Management

Bookings table
- Install TanStack Table (react-table)
- BookingsTable component
- Columns:
  - Booking number (link)
  - Status badge
  - Origin → Destination
  - ETD / ETA
  - Carrier + container number
  - Shipper / Consignee
  - Actions dropdown
- Sortable columns
- Row selection (checkboxes)
- Responsive table (mobile: cards, desktop: table)
Filtering & search
- FilterPanel component
- Global search input (fuzzy)
- Status filter (multi-select)
- Date range picker
- Carrier filter
- Origin/destination filters
- Clear all filters button
- URL state sync (filters persist on refresh)
Bulk actions
- Export selected bookings
- Bulk status update (if applicable)
- Delete/cancel multiple bookings (with confirmation)
Export functionality
- Export to CSV button
- Export to Excel button (using xlsx library)
- Export with current filters applied
- Download progress indicator
Performance optimization
- Virtual scrolling for large lists
- Lazy loading of data (infinite scroll or pagination)
- Optimistic updates
- Debounced search input

Sprint 21-22: Additional Carrier Integrations (2 weeks)

Week 23: MSC & CMA CGM Connectors

MSC integration
- Research MSC API documentation
- Obtain MSC API credentials
- Implement MSCConnectorAdapter
- Implement MSCRequestMapper
- Implement MSCResponseMapper
- Handle MSC-specific error codes
- Add circuit breaker and retry logic
- Unit tests
- Integration tests with sandbox
CMA CGM integration
- Research CMA CGM WebAccess API
- Obtain API credentials
- Implement CMACGMConnectorAdapter
- Implement CMACGMRequestMapper
- Implement CMACGMResponseMapper
- Handle CMA CGM-specific error codes
- Add circuit breaker and retry logic
- Unit tests
- Integration tests
Connector registry
- Update CarrierConnectorFactory to include new connectors
- Add carrier configuration to database
- Admin UI to enable/disable carriers

Week 24: Hapag-Lloyd & ONE Connectors

Hapag-Lloyd integration
- Research Hapag-Lloyd Quick Quotes API
- Obtain API credentials
- Implement HapagLloydConnectorAdapter
- Implement request/response mappers
- Error handling and resilience
- Tests
ONE (Ocean Network Express) integration
- Research ONE API
- Obtain API credentials
- Implement ONEConnectorAdapter
- Implement request/response mappers
- Error handling and resilience
- Tests
Carrier management
- Add carrier configuration page in admin UI
- Enable/disable carriers dynamically
- Monitor carrier API health
- Carrier-specific rate limiting configuration
Integration monitoring
- Add metrics for each carrier:
  - Response time
  - Success rate
  - Error rate
  - Timeout rate
- Create monitoring dashboard (Grafana or custom)
- Setup alerts for carrier downtime

📅 PHASE 4 - POLISH, TESTING & LAUNCH (2-4 weeks)

Sprint 23: Security, Performance & Testing (1-2 weeks)

Week 25: Security Hardening

Security audit
- Run OWASP ZAP security scan
- Review OWASP Top 10 compliance
- Check for SQL injection vulnerabilities
- Test XSS prevention
- Verify CSRF protection
- Test authentication & authorization edge cases
Data protection
- Ensure all passwords are hashed (bcrypt/Argon2)
- Verify JWT token security
- Implement token rotation
- Add API rate limiting per user
- Implement brute-force protection
- Secure file upload validation (file type, size, virus scan)
Compliance & privacy
- Add Terms & Conditions page
- Add Privacy Policy page
- Implement GDPR compliance features:
  - Data export
  - Data deletion
  - Consent management
- Add Cookie consent banner
Infrastructure security
- Enable HTTPS/TLS 1.3
- Configure security headers (helmet.js)
- Setup WAF (Web Application Firewall)
- Database encryption at rest
- Secure environment variable management
- Implement secrets rotation

Week 26: Performance & Load Testing

Backend performance
- Database query optimization (analyze slow queries)
- Add database connection pooling
- Optimize N+1 queries
- Add caching for frequently accessed data
- Implement API response compression (gzip)
- Add CDN for static assets
Frontend performance
- Optimize bundle size (code splitting)
- Implement lazy loading for routes
- Optimize images (WebP, lazy loading)
- Add service worker for offline support
- Implement skeleton screens
- Reduce JavaScript execution time
Load testing
- Create load test scenarios (k6 or Artillery)
- Test rate search endpoint (target: 100 req/s)
- Test booking creation (target: 50 req/s)
- Test dashboard API (target: 200 req/s)
- Identify and fix bottlenecks
- Verify auto-scaling works (if cloud-deployed)
Monitoring setup
- Setup APM (Application Performance Monitoring)
- Configure error tracking (Sentry)
- Setup uptime monitoring (Pingdom, UptimeRobot)
- Create performance dashboards
- Setup alerts for performance degradation

Sprint 24: E2E Testing & Documentation (1-2 weeks)

Week 27: Comprehensive Testing

E2E test suite
- Install Playwright or Cypress
- Test: Complete user registration flow
- Test: Login with OAuth
- Test: Search rates and view results
- Test: Complete booking workflow (all 4 steps)
- Test: View booking in dashboard
- Test: Edit booking
- Test: Cancel booking
- Test: User management (invite, change role)
- Test: Organization settings update
- Run tests in CI/CD pipeline
API testing
- Create Postman collection
- Document all API endpoints
- Add example requests/responses
- Create automated API tests
- Test error scenarios
Accessibility testing
- Run axe-core audits
- Test keyboard navigation
- Test screen reader compatibility
- Ensure WCAG 2.1 AA compliance
- Fix accessibility issues
Browser & device testing
- Test on Chrome, Firefox, Safari, Edge
- Test on iOS (Safari)
- Test on Android (Chrome)
- Test on different screen sizes
- Fix cross-browser issues

Week 28: Documentation & Deployment Prep

User documentation
- Create user guide (how to search rates)
- Create booking guide
- Create dashboard guide
- Add FAQ section
- Create video tutorials (optional)
Developer documentation
- Update README.md with setup instructions
- Document architecture decisions (ADRs)
- Document API (OpenAPI spec)
- Create contribution guide
- Document deployment process
Admin documentation
- Create runbook for common issues
- Document backup/restore procedures
- Document monitoring and alerting
- Create incident response plan
Deployment infrastructure
- Setup production environment (AWS/GCP/Azure)
- Configure CI/CD for production deployment
- Setup database backups (automated daily)
- Configure SSL certificates
- Setup domain and DNS
- Configure email service for production
- Setup S3 buckets for production
Pre-launch checklist
- Verify all environment variables set
- Run final security audit
- Perform load testing on production-like environment
- Test disaster recovery procedures
- Verify monitoring and alerting works
- Create launch communication plan

📅 GO-TO-MARKET (2 weeks)

Week 29: Beta Testing & Feedback

Beta program
- Recruit 5-10 beta testers (freight forwarders)
- Create beta testing guide
- Setup feedback collection (surveys, interviews)
- Monitor beta user activity
- Fix critical bugs reported by beta users
Onboarding early adopters
- Create personalized onboarding for each early adopter
- Schedule 1:1 demo sessions
- Provide dedicated support channel (Slack/email)
- Collect feature requests
- Track usage metrics
Marketing materials
- Create landing page
- Create product demo video
- Prepare sales pitch deck
- Create case studies (if available)
- Setup analytics (Google Analytics, Mixpanel)

Week 30: Launch & Support

Official launch
- Deploy to production
- Announce launch to beta users
- Launch marketing campaign
- Monitor system performance closely
- Be ready for immediate hotfixes
Support infrastructure
- Setup support email (support@xpeditis.com)
- Create ticketing system (Zendesk/Intercom)
- Prepare support team training
- Create support SLAs
- Setup on-call rotation
Metrics tracking
- Track KPIs daily:
  - Number of active users (DAU/MAU)
  - Number of bookings created
  - Search-to-booking conversion rate
  - Average booking value
  - Carrier API error rates
  - Cache hit ratio
  - User retention rate
- Weekly analytics review meetings
- Create investor/stakeholder reports
Continuous improvement
- Setup feature request tracking
- Prioritize post-MVP features
- Plan next sprint based on user feedback
- Monitor competitor activities
- Iterate based on data

📊 SUCCESS METRICS (MVP)

Technical Metrics

✅ Rate search response time: <2s for 90% of requests
✅ Dashboard load time: <1s for up to 5k bookings
✅ Carrier API timeout: 5s max
✅ Cache hit ratio: >90%
✅ API uptime: >99.5%
✅ Test coverage: Domain 90%, Application 80%, Infrastructure 70%

Business Metrics

✅ 10-20 active freight forwarder organizations
✅ 50-100 bookings per month
✅ Search-to-booking conversion rate: ≥3%
✅ User retention at 3 months: >60%
✅ Average time to create booking: <5 minutes

🚨 RISK MITIGATION

Critical Risks

Carrier API access delays: Start with 1-2 carriers, use mock data for demos
Performance issues: Implement caching early, load test continuously
Security vulnerabilities: Security audit at each phase, not just at the end
User adoption: Close collaboration with beta users, iterate quickly based on feedback

Contingency Plans

Carrier API unavailable: Have fallback to aggregated/spot pricing data
Infrastructure failure: Multi-region deployment, automated backups
Key developer unavailable: Document everything, pair programming
Budget overrun: Prioritize ruthlessly, MVP-first approach

📝 NOTES

This roadmap is aggressive but achievable with a focused team
Prioritize ruthlessly: Rate search, booking, and at least 1 carrier integration are CRITICAL
Test early and often - don't wait until the end
Get user feedback as early as Week 10-12 (even with incomplete features)
Weekly demos to stakeholders to maintain alignment
Bi-weekly retrospectives to adjust the plan

Last updated: [Date] Maintained by: [Team Lead]

40 KiB Raw Blame History

TODO - Xpeditis MVP Implementation Roadmap

📅 SPRINT 0 - PROJECT SETUP & INFRASTRUCTURE (2 weeks)

Week 1: Repository & Development Environment

Week 2: CI/CD, Documentation & Core Infrastructure

📅 PHASE 1 - CORE SEARCH & CARRIER INTEGRATION (6-8 weeks)

Sprint 1-2: Domain Layer & Port Definitions (2 weeks)

Week 3: Domain Entities & Value Objects

Week 4: Ports & Domain Services

Sprint 3-4: Infrastructure Layer - Persistence & Cache (2 weeks)

Week 5: Database & Repositories

Week 6: Redis Cache & Carrier Connectors Foundation

Sprint 5-6: Application Layer & Rate Search API (2 weeks)

Week 7: DTOs, Mappers & Controllers

Week 8: API Documentation, Testing & Optimization

Sprint 7-8: Frontend Rate Search UI (2 weeks)

Week 9: Search Form & State Management

Week 10: Results Display & Filtering

📅 PHASE 2 - BOOKING & USER MANAGEMENT (6-8 weeks)

Sprint 9-10: Authentication System (2 weeks)

Week 11: Backend Authentication

Week 12: Organization & RBAC

Sprint 11-12: Frontend Authentication (2 weeks)

Week 13: Auth UI Components

Week 14: Organization & User Management UI

Sprint 13-14: Booking Workflow Backend (2 weeks)

Week 15: Booking Domain & API

Week 16: Email & Document Generation

Sprint 15-16: Booking Workflow Frontend (2 weeks)

Week 17: Multi-Step Booking Form

Week 18: Booking Confirmation & Management

📅 PHASE 3 - DASHBOARD & ADDITIONAL CARRIERS (4-6 weeks)

Sprint 17-18: Dashboard Backend & Analytics (2 weeks)

Week 19: Dashboard API & Analytics

Week 20: Audit Logs & Notifications

Sprint 19-20: Dashboard Frontend (2 weeks)

Week 21: Dashboard UI Components

Week 22: Bookings List & Management

Sprint 21-22: Additional Carrier Integrations (2 weeks)

Week 23: MSC & CMA CGM Connectors

Week 24: Hapag-Lloyd & ONE Connectors

📅 PHASE 4 - POLISH, TESTING & LAUNCH (2-4 weeks)

Sprint 23: Security, Performance & Testing (1-2 weeks)

Week 25: Security Hardening

Week 26: Performance & Load Testing

Sprint 24: E2E Testing & Documentation (1-2 weeks)

Week 27: Comprehensive Testing

Week 28: Documentation & Deployment Prep

📅 GO-TO-MARKET (2 weeks)

Week 29: Beta Testing & Feedback

Week 30: Launch & Support

📊 SUCCESS METRICS (MVP)

Technical Metrics

Business Metrics

🚨 RISK MITIGATION

Critical Risks

Contingency Plans

📝 NOTES

40 KiB

Raw Blame History