xpeditis2.0/docs/architecture/ARCHITECTURE.md

# Xpeditis 2.0 - Architecture Documentation

## 📋 Table of Contents

1. [Overview](#overview)
2. [System Architecture](#system-architecture)
3. [Hexagonal Architecture](#hexagonal-architecture)
4. [Technology Stack](#technology-stack)
5. [Core Components](#core-components)
6. [Security Architecture](#security-architecture)
7. [Performance & Scalability](#performance--scalability)
8. [Monitoring & Observability](#monitoring--observability)
9. [Deployment Architecture](#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

```typescript
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)

```typescript
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):
```json
{
  "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