xpeditis2.0/docs/architecture/ARCHITECTURE.md

Xpeditis 2.0 - Architecture Documentation

📋 Table of Contents

1. Overview
2. System Architecture
3. Hexagonal Architecture
4. Technology Stack
5. Core Components
6. Security Architecture
7. Performance & Scalability
8. Monitoring & Observability
9. Deployment Architecture

---

Overview

Xpeditis is a B2B SaaS maritime freight booking and management platform built with a modern, scalable architecture following hexagonal architecture principles (Ports & Adapters).

Business Goals

• Enable freight forwarders to search and compare real-time shipping rates
• Streamline the booking process for container shipping
• Provide centralized dashboard for shipment management
• Support 50-100 bookings/month for 10-20 early adopter freight forwarders

---

System Architecture

High-Level Architecture

┌─────────────────────────────────────────────────────────────────┐
│                          Frontend Layer                          │
│  (Next.js + React + TanStack Table + Socket.IO Client)          │
└────────────────────────┬────────────────────────────────────────┘
                         │
                         │ HTTPS/WSS
                         │
┌────────────────────────▼────────────────────────────────────────┐
│                       API Gateway Layer                          │
│  (NestJS + Helmet.js + Rate Limiting + JWT Auth)                │
└────────────────────────┬────────────────────────────────────────┘
                         │
         ┌───────────────┼───────────────┬──────────────┐
         │               │               │              │
         ▼               ▼               ▼              ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│   Booking   │ │    Rate     │ │    User     │ │   Audit     │
│   Service   │ │   Service   │ │   Service   │ │   Service   │
└──────┬──────┘ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘
       │               │               │              │
       │      ┌────────┴────────┐      │              │
       │      │                 │      │              │
       ▼      ▼                 ▼      ▼              ▼
┌─────────────────────────────────────────────────────────────┐
│                  Infrastructure Layer                        │
│  (PostgreSQL + Redis + S3 + Carrier APIs + WebSocket)       │
└─────────────────────────────────────────────────────────────┘

---

Hexagonal Architecture

The codebase follows hexagonal architecture (Ports & Adapters) with strict separation of concerns:

Layer Structure

apps/backend/src/
├── domain/                    # 🎯 Core Business Logic (NO external dependencies)
│   ├── entities/              # Business entities
│   │   ├── booking.entity.ts
│   │   ├── rate-quote.entity.ts
│   │   ├── user.entity.ts
│   │   └── ...
│   ├── value-objects/         # Immutable value objects
│   │   ├── email.vo.ts
│   │   ├── money.vo.ts
│   │   └── booking-number.vo.ts
│   └── ports/
│       ├── in/                # API Ports (use cases)
│       │   ├── search-rates.port.ts
│       │   └── create-booking.port.ts
│       └── out/               # SPI Ports (infrastructure interfaces)
│           ├── booking.repository.ts
│           └── carrier-connector.port.ts
│
├── application/               # 🔌 Controllers & DTOs (depends ONLY on domain)
│   ├── controllers/
│   ├── services/
│   ├── dto/
│   ├── guards/
│   └── interceptors/
│
└── infrastructure/            # 🏗️ External integrations (depends ONLY on domain)
    ├── persistence/
    │   └── typeorm/
    │       ├── entities/      # ORM entities
    │       └── repositories/  # Repository implementations
    ├── carriers/              # Carrier API connectors
    ├── cache/                 # Redis cache
    ├── security/              # Security configuration
    └── monitoring/            # Sentry, APM

Dependency Rules

1. Domain Layer: Zero external dependencies (pure TypeScript)
2. Application Layer: Depends only on domain
3. Infrastructure Layer: Depends only on domain
4. Dependency Direction: Always points inward toward domain

---

Technology Stack

Backend

• Framework: NestJS 10.x (Node.js)
• Language: TypeScript 5.3+
• ORM: TypeORM 0.3.17
• Database: PostgreSQL 15+ with pg_trgm extension
• Cache: Redis 7+ (ioredis)
• Authentication: JWT (jsonwebtoken, passport-jwt)
• Validation: class-validator, class-transformer
• Documentation: Swagger/OpenAPI (@nestjs/swagger)

Frontend

• Framework: Next.js 14.x (React 18)
• Language: TypeScript
• UI Library: TanStack Table v8, TanStack Virtual
• Styling: Tailwind CSS
• Real-time: Socket.IO Client
• File Export: xlsx, file-saver

Infrastructure

• Security: Helmet.js, @nestjs/throttler
• Monitoring: Sentry (@sentry/node, @sentry/profiling-node)
• Load Balancing: (AWS ALB / GCP Load Balancer)
• Storage: S3-compatible (AWS S3 / MinIO)
• Email: Nodemailer with MJML templates

Testing

• Unit Tests: Jest
• E2E Tests: Playwright
• Load Tests: K6
• API Tests: Postman/Newman

---

Core Components

1. Rate Search Engine

Purpose: Search and compare shipping rates from multiple carriers

Flow:

User Request → Rate Search Controller → Rate Search Service
                                             ↓
                        Check Redis Cache (15min TTL)
                                             ↓
                        Query Carrier APIs (parallel, 5s timeout)
                                             ↓
                        Normalize & Aggregate Results
                                             ↓
                        Store in Cache → Return to User

Performance Targets:

• Response Time: <2s for 90% of requests (with cache)
• Cache Hit Ratio: >90% for common routes
• Carrier Timeout: 5 seconds with circuit breaker

2. Booking Management

Purpose: Create and manage container bookings

Flow:

Create Booking Request → Validation → Booking Service
                                            ↓
                        Generate Booking Number (WCM-YYYY-XXXXXX)
                                            ↓
                        Persist to PostgreSQL
                                            ↓
                        Trigger Audit Log
                                            ↓
                        Send Notification (WebSocket)
                                            ↓
                        Trigger Webhooks
                                            ↓
                        Send Email Confirmation

Business Rules:

• Booking workflow: ≤4 steps maximum
• Rate quotes expire after 15 minutes
• Booking numbers format: WCM-YYYY-XXXXXX

3. Audit Logging System

Purpose: Track all user actions for compliance and debugging

Features:

• 26 Action Types: BOOKING_CREATED, USER_UPDATED, etc.
• 3 Status Levels: SUCCESS, FAILURE, WARNING
• Never Blocks: Wrapped in try-catch, errors logged but not thrown
• Filterable: By user, action, resource, date range

Storage: PostgreSQL with indexes on (userId, action, createdAt)

4. Real-Time Notifications

Purpose: Push notifications to users via WebSocket

Architecture:

Server Event → NotificationService → Create Notification in DB
                                            ↓
                        NotificationsGateway (Socket.IO)
                                            ↓
                        Emit to User Room (userId)
                                            ↓
                        Client Receives Notification

Features:

• JWT Authentication: Tokens verified on WebSocket connection
• User Rooms: Each user joins their own room
• 9 Notification Types: BOOKING_CREATED, DOCUMENT_UPLOADED, etc.
• 4 Priority Levels: LOW, MEDIUM, HIGH, URGENT

5. Webhook System

Purpose: Allow third-party integrations to receive event notifications

Security:

• HMAC SHA-256 Signatures: Payload signed with secret
• Retry Logic: 3 attempts with exponential backoff
• Circuit Breaker: Mark as FAILED after exhausting retries

Events Supported: BOOKING_CREATED, BOOKING_UPDATED, RATE_QUOTED, etc.

---

Security Architecture

OWASP Top 10 Protection

1. Injection Prevention

• Parameterized Queries: TypeORM prevents SQL injection
• Input Validation: class-validator on all DTOs
• Output Encoding: Automatic by NestJS

2. Broken Authentication

• JWT with Short Expiry: Access tokens expire in 15 minutes
• Refresh Tokens: 7-day expiry with rotation
• Brute Force Protection: Exponential backoff after 3 failed attempts
• Password Policy: Min 12 chars, complexity requirements

3. Sensitive Data Exposure

• TLS 1.3: All traffic encrypted
• Password Hashing: bcrypt/Argon2id (≥12 rounds)
• JWT Secrets: Stored in environment variables
• Database Encryption: At rest (AWS RDS / GCP Cloud SQL)

4. XML External Entities (XXE)

• No XML Parsing: JSON-only API

5. Broken Access Control

• RBAC: 4 roles (Admin, Manager, User, Viewer)
• JWT Auth Guard: Global guard on all routes
• Organization Isolation: Users can only access their org data

6. Security Misconfiguration

• Helmet.js: Security headers (CSP, HSTS, XSS, etc.)
• CORS: Strict origin validation
• Error Handling: No sensitive info in error responses

7. Cross-Site Scripting (XSS)

• Content Security Policy: Strict CSP headers
• Input Sanitization: class-validator strips malicious input
• Output Encoding: React auto-escapes

8. Insecure Deserialization

• No Native Deserialization: JSON.parse with validation

9. Using Components with Known Vulnerabilities

• Regular Updates: npm audit, Dependabot
• Security Scanning: Snyk, GitHub Advanced Security

10. Insufficient Logging & Monitoring

• Sentry: Error tracking and APM
• Audit Logs: All actions logged
• Performance Monitoring: Response times, error rates

Rate Limiting

Global: 100 req/min
Auth: 5 req/min (login)
Search: 30 req/min
Booking: 20 req/min

File Upload Security

• Max Size: 10MB
• Allowed Types: PDF, images, CSV, Excel
• Mime Type Validation: Check file signature (magic numbers)
• Filename Sanitization: Remove special characters
• Virus Scanning: ClamAV integration (production)

---

Performance & Scalability

Caching Strategy

┌────────────────────────────────────────────────────┐
│              Redis Cache (15min TTL)                │
├────────────────────────────────────────────────────┤
│  Top 100 Trade Lanes (pre-fetched on startup)      │
│  Spot Rates (invalidated on carrier API update)    │
│  User Sessions (JWT blacklist)                     │
└────────────────────────────────────────────────────┘

Cache Hit Target: >90% for common routes

Database Optimization

1. Indexes:

   • bookings(userId, status, createdAt)
   • audit_logs(userId, action, createdAt)
   • notifications(userId, read, createdAt)

2. Query Optimization:

   • Avoid N+1 queries (use leftJoinAndSelect)
   • Pagination on all list endpoints
   • Connection pooling (max 20 connections)

3. Fuzzy Search:

   • PostgreSQL pg_trgm extension
   • GIN indexes on searchable fields
   • Similarity threshold: 0.3

API Response Compression

• gzip Compression: Enabled via compression middleware
• Average Reduction: 70-80% for JSON responses

Frontend Performance

1. Code Splitting: Next.js automatic code splitting
2. Lazy Loading: Routes loaded on demand
3. Virtual Scrolling: TanStack Virtual for large tables
4. Image Optimization: Next.js Image component

Scalability

Horizontal Scaling:

• Stateless backend (JWT auth, no sessions)
• Redis for shared state
• Load balancer distributes traffic

Vertical Scaling:

• PostgreSQL read replicas
• Redis clustering
• Database sharding (future)

---

Monitoring & Observability

Error Tracking (Sentry)

Environment: production
Trace Sample Rate: 0.1 (10%)
Profile Sample Rate: 0.05 (5%)
Filtered Errors: ECONNREFUSED, ETIMEDOUT

Performance Monitoring

Metrics Tracked:

• Response Times: p50, p95, p99
• Error Rates: By endpoint, user, organization
• Cache Hit Ratio: Redis cache performance
• Database Query Times: Slow query detection
• Carrier API Latency: Per carrier tracking

Alerts

1. Critical: Error rate >5%, Response time >5s
2. Warning: Error rate >1%, Response time >2s
3. Info: Cache hit ratio <80%

Logging

Structured Logging (Pino):

{
  "level": "info",
  "timestamp": "2025-10-14T12:00:00Z",
  "context": "BookingService",
  "userId": "user-123",
  "organizationId": "org-456",
  "message": "Booking created successfully",
  "metadata": {
    "bookingId": "booking-789",
    "bookingNumber": "WCM-2025-ABC123"
  }
}

---

Deployment Architecture

Production Environment (AWS Example)

┌──────────────────────────────────────────────────────────────┐
│                         CloudFront CDN                        │
│                  (Frontend Static Assets)                     │
└────────────────────────────┬─────────────────────────────────┘
                             │
┌────────────────────────────▼─────────────────────────────────┐
│                    Application Load Balancer                  │
│                  (SSL Termination, WAF)                       │
└────────────┬───────────────────────────────┬─────────────────┘
             │                               │
             ▼                               ▼
┌─────────────────────────┐     ┌─────────────────────────┐
│    ECS/Fargate Tasks    │     │    ECS/Fargate Tasks    │
│  (Backend API Servers)  │     │  (Backend API Servers)  │
│    Auto-scaling 2-10    │     │    Auto-scaling 2-10    │
└────────────┬────────────┘     └────────────┬────────────┘
             │                               │
             └───────────────┬───────────────┘
                             │
         ┌───────────────────┼───────────────────┐
         │                   │                   │
         ▼                   ▼                   ▼
┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
│   RDS Aurora    │  │  ElastiCache    │  │       S3        │
│   PostgreSQL    │  │   (Redis)       │  │  (Documents)    │
│   Multi-AZ      │  │   Cluster       │  │   Versioning    │
└─────────────────┘  └─────────────────┘  └─────────────────┘

Infrastructure as Code (IaC)

• Terraform: AWS/GCP/Azure infrastructure
• Docker: Containerized applications
• CI/CD: GitHub Actions

Backup & Disaster Recovery

1. Database Backups: Automated daily, retained 30 days
2. S3 Versioning: Enabled for all documents
3. Disaster Recovery: RTO <1 hour, RPO <15 minutes

---

Architecture Decisions

ADR-001: Hexagonal Architecture

Decision: Use hexagonal architecture (Ports & Adapters) Rationale: Enables testability, flexibility, and framework independence Trade-offs: Higher initial complexity, but long-term maintainability

ADR-002: PostgreSQL for Primary Database

Decision: Use PostgreSQL instead of NoSQL Rationale: ACID compliance, relational data model, fuzzy search (pg_trgm) Trade-offs: Scaling requires read replicas vs. automatic horizontal scaling

ADR-003: Redis for Caching

Decision: Cache rate quotes in Redis with 15-minute TTL Rationale: Reduce carrier API calls, improve response times Trade-offs: Stale data risk, but acceptable for freight rates

ADR-004: JWT Authentication

Decision: Use JWT with short-lived access tokens (15 minutes) Rationale: Stateless auth, scalable, industry standard Trade-offs: Token revocation complexity, mitigated with refresh tokens

ADR-005: WebSocket for Real-Time Notifications

Decision: Use Socket.IO for real-time push notifications Rationale: Bi-directional communication, fallback to polling Trade-offs: Increased server connections, but essential for UX

---

Performance Targets

Metric	Target	Actual (Phase 3)
Rate Search (with cache)	<2s (p90)	~500ms
Booking Creation	<3s	~1s
Dashboard Load (5k bookings)	<1s	TBD
Cache Hit Ratio	>90%	TBD
API Uptime	99.9%	TBD
Test Coverage	>80%	82% (Phase 3)

---

Security Compliance

GDPR Features

• Data Export: Users can export their data (JSON/CSV)
• Data Deletion: Users can request account deletion
• Consent Management: Cookie consent banner
• Privacy Policy: Comprehensive privacy documentation

OWASP Compliance

• ✅ Helmet.js security headers
• ✅ Rate limiting (user-based)
• ✅ Brute-force protection
• ✅ Input validation (class-validator)
• ✅ Output encoding (React auto-escape)
• ✅ HTTPS/TLS 1.3
• ✅ JWT with rotation
• ✅ Audit logging

---

Future Enhancements

1. Carrier Integrations: Add 10+ carriers
2. Mobile App: React Native iOS/Android
3. Analytics Dashboard: Business intelligence
4. Payment Integration: Stripe/PayPal
5. Multi-Currency: Dynamic exchange rates
6. AI/ML: Rate prediction, route optimization

---

Document Version: 1.0.0 Last Updated: October 14, 2025 Author: Xpeditis Development Team