# 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
    ```typescript
    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
    ```typescript
    interface CarrierConnectorPort {
      searchRates(input: RateSearchInput): Promise<RateQuote[]>;
      checkAvailability(input: AvailabilityInput): Promise<boolean>;
    }
    ```
  - [ ] `CachePort` interface
    ```typescript
    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`
    ```typescript
    {
      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`
    ```typescript
    {
      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)

#### Week 9: Search Form & State Management

- [ ] **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
    ```typescript
    @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
    ```typescript
    {
      id, bookingNumber, userId, orgId,
      rateQuoteId, shipper, consignee, notifyParty,
      containers[], cargoDetails, specialInstructions,
      status, createdAt, updatedAt
    }
    ```
  - [ ] `Container` entity (detailed)
    ```typescript
    {
      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]