de.arch - Core Architecture Server

The central backend providing APIs for logistics operations, workspace management, and service coordination.

Service Overview

de.arch is the core API server that powers logistics operations across the De. platform. It handles fleet management, warehouse operations, pricing, shipments, and workspace administration.

Base URL: https://api.dedot.io

Architecture Overview

de.arch Components

Key Features

LSP Operations

Complete logistics provider API with fleet, warehouse, and pricing management

Workspace Management

Multi-tenant workspace administration with billing and subscriptions

Agent Coordination

Driver dispatch, navigation, and real-time tracking

Client Services

Customer-facing APIs for orders, preferences, and tracking

Real-time Events

WebSocket and Socket.IO for live updates and notifications

Mapbox Integration

Routing, geocoding, and navigation services

Technology Stack

Tech Stack

Component

Technology

Purpose

Web Framework

Fastify

High-performance HTTP server

Database

MongoDB

Primary data storage

Real-time

Socket.IO

WebSocket connections

Cache

Redis

Caching and pub/sub

Maps

Mapbox SDK

Routing and geocoding

API Modules

1. LSP API

Logistics Service Provider operations for carriers and delivery companies.

Fleet Management

Vehicles (registration, tracking, maintenance)
Drivers (assignment, availability, performance)
Parking locations and zones
Maintenance scheduling

Warehouse Operations

Warehouse management
Inventory tracking
Inbound shipment processing
Hub coordination

Pricing Engine

Contract management
Pricing templates and tiers
Usage-based billing
Dynamic adjustments

Operations

Shipment tracking
Coverage area management
Carrier integration
Reporting and analytics

View LSP API Documentation →

2. Workspace API

Multi-tenant workspace administration and management.

Features:

Workspace creation and configuration
Access control and permissions
Billing and subscription management
Service provider connectors (LSP, CSP, IoTSP, DEV)
Admin user management

View Workspace API Documentation →

3. Agents API

Driver and agent coordination with real-time tracking.

Features:

Driver profile management
Navigation and routing
Ride/delivery assignment
Real-time location updates
Performance tracking

View Agents API Documentation →

4. Clients API

Customer-facing services for orders and tracking.

Features:

Order placement and management
Delivery preferences
Real-time tracking
Order history
Notifications

View Clients API Documentation →

Data Models

Order/Shipment

typescript

interface Order {
  id: string
  workspace: string
  type: 'delivery' | 'pickup' | 'return'
  status: 'pending' | 'assigned' | 'in_transit' | 'delivered' | 'cancelled'
  
  customer: {
    uid: string
    name: string
    phone: string
    email?: string
  }
  
  pickup: {
    address: string
    coordinates: { lng: number; lat: number }
    contactName?: string
    contactPhone?: string
    scheduledAt?: string
  }
  
  delivery: {
    address: string
    coordinates: { lng: number; lat: number }
    contactName?: string
    contactPhone?: string
    scheduledAt?: string
    instructions?: string
  }
  
  items: Array<{
    name: string
    quantity: number
    weight?: number
    dimensions?: { length: number; width: number; height: number }
    value?: number
  }>
  
  agent?: {
    uid: string
    name: string
    phone: string
    vehicle: string
  }
  
  tracking: {
    events: Array<{
      type: string
      timestamp: string
      location?: { lng: number; lat: number }
      notes?: string
    }>
    eta?: string
    currentLocation?: { lng: number; lat: number }
  }
  
  pricing: {
    subtotal: number
    tax: number
    fees: number
    total: number
    currency: string
  }
  
  metadata?: Record<string, any>
  createdAt: string
  updatedAt: string
}

Vehicle

typescript

interface Vehicle {
  id: string
  workspace: string
  lsp: string
  
  info: {
    make: string
    model: string
    year: number
    licensePlate: string
    vin?: string
    color?: string
  }
  
  type: 'car' | 'van' | 'truck' | 'motorcycle' | 'bicycle'
  capacity: {
    weight: number
    volume: number
    passengers?: number
  }
  
  status: 'active' | 'inactive' | 'maintenance' | 'retired'
  
  location?: {
    coordinates: { lng: number; lat: number }
    heading?: number
    speed?: number
    lastUpdated: string
  }
  
  driver?: {
    uid: string
    name: string
    assignedAt: string
  }
  
  maintenance: {
    lastService: string
    nextService: string
    mileage: number
  }
  
  createdAt: string
  updatedAt: string
}

Warehouse

typescript

interface Warehouse {
  id: string
  workspace: string
  lsp: string
  
  name: string
  code: string
  type: 'distribution' | 'fulfillment' | 'storage' | 'cross_dock'
  
  location: {
    address: string
    coordinates: { lng: number; lat: number }
    timezone: string
  }
  
  contact: {
    name: string
    phone: string
    email: string
  }
  
  capacity: {
    area: number
    volume: number
    zones: number
  }
  
  hours: {
    [day: string]: {
      open: string
      close: string
    }
  }
  
  zones: Array<{
    id: string
    name: string
    type: 'receiving' | 'storage' | 'picking' | 'packing' | 'shipping'
    capacity: number
  }>
  
  status: 'active' | 'inactive' | 'temporary_closed'
  createdAt: string
  updatedAt: string
}

Real-time Features

WebSocket Connection

typescript

import io from 'socket.io-client'

const socket = io('wss://api.dedot.io', {
  auth: {
    token: accessToken
  }
})

// Listen for order updates
socket.on('order:updated', (data) => {
  console.log('Order status changed:', data)
})

// Listen for driver location updates
socket.on('driver:location', (data) => {
  console.log('Driver moved:', data.location)
})

// Subscribe to specific order
socket.emit('subscribe', {
  channel: 'order',
  id: 'order_123'
})

Event Types

Real-time Events

Event

Description

Payload

order:created

New order placed

Order object

order:assigned

Driver assigned to order

Order + Agent info

order:in_transit

Order picked up

Order + Location

order:delivered

Order completed

Order + Proof

driver:location

Driver location update

Coordinates + Heading

vehicle:status

Vehicle status change

Vehicle + Status

Configuration

Environment Variables

bash

# Server
ARCH_PORT=3000
ARCH_HOST=0.0.0.0

# Database
MONGODB_URI=mongodb://localhost:27017/de-arch
MONGODB_DATABASE=de-arch

# Redis
REDIS_URL=redis://localhost:6379

# Mapbox
MAPBOX_ACCESS_TOKEN=your-mapbox-token

# Authentication
AUTH_SERVICE_URL=https://auth.dedot.io

# WebSocket
SOCKET_IO_CORS_ORIGIN=*
SOCKET_IO_PING_TIMEOUT=60000

# External Services
IOT_SERVICE_URL=https://iot.dedot.io

Usage Examples

Create Order

typescript

import De from '@de./sdk'

const access = new De.Access({
  workspace: 'your-workspace-id',
  accessToken: 'your-access-token',
  env: 'prod'
})

const order = await access.request({
  url: '/orders',
  method: 'POST',
  body: {
    type: 'delivery',
    customer: {
      uid: 'user_123',
      name: 'John Doe',
      phone: '+1234567890'
    },
    pickup: {
      address: '123 Main St, New York, NY 10001',
      coordinates: { lng: -74.0060, lat: 40.7128 }
    },
    delivery: {
      address: '456 Oak Ave, New York, NY 10002',
      coordinates: { lng: -73.9855, lat: 40.7580 },
      instructions: 'Ring doorbell'
    },
    items: [
      {
        name: 'Package A',
        quantity: 1,
        weight: 5
      }
    ]
  }
})

console.log('Order created:', order.data.id)

Track Order

typescript

// Get order details
const order = await access.request({
  url: `/orders/${orderId}`,
  method: 'GET'
})

console.log('Order status:', order.data.status)
console.log('ETA:', order.data.tracking.eta)

// Real-time tracking
const socket = io('wss://api.dedot.io', {
  auth: { token: accessToken }
})

socket.emit('subscribe', {
  channel: 'order',
  id: orderId
})

socket.on('order:updated', (data) => {
  console.log('Status update:', data.status)
  updateUI(data)
})

socket.on('driver:location', (data) => {
  console.log('Driver location:', data.location)
  updateMap(data.location)
})

Manage Fleet

typescript

// Get all vehicles
const vehicles = await access.request({
  url: '/lsp/fleets/vehicles',
  method: 'GET',
  query: {
    status: 'active',
    limit: 50
  }
})

// Update vehicle location
await access.request({
  url: `/lsp/fleets/vehicles/${vehicleId}/location`,
  method: 'PATCH',
  body: {
    coordinates: { lng: -74.0060, lat: 40.7128 },
    heading: 45,
    speed: 35
  }
})

// Schedule maintenance
await access.request({
  url: `/lsp/fleets/maintenance`,
  method: 'POST',
  body: {
    vehicleId: vehicleId,
    type: 'oil_change',
    scheduledAt: '2024-02-01T10:00:00Z',
    notes: 'Regular 5000 mile service'
  }
})

Performance Optimization

Caching StrategyAPI responses cached in Redis (5 min TTL)
Vehicle locations cached (30 sec TTL)
Order status cached until update
Invalidation on write operations

Database IndexingGeospatial indexes on coordinates
Compound indexes on common queries
Text indexes for search
TTL indexes for temporary data

Connection PoolingMongoDB: 100 max connections
Redis: 50 max connections
Socket.IO: 10,000 concurrent connections
Connection reuse and management

Rate Limiting1000 requests/min per workspace
100 WebSocket subscriptions per connection
Burst allowance: 2x normal limit
Graceful degradation

Deployment

Docker Compose

yaml

version: '3.8'

services:
  de-arch:
    image: dedot/de-arch:latest
    ports:
      - "3000:3000"
    environment:
      - MONGODB_URI=mongodb://mongo:27017/de-arch
      - REDIS_URL=redis://redis:6379
      - MAPBOX_ACCESS_TOKEN=${MAPBOX_ACCESS_TOKEN}
      - AUTH_SERVICE_URL=http://de-auth:3001
    depends_on:
      - mongo
      - redis
    networks:
      - de-network

  mongo:
    image: mongo:6
    volumes:
      - arch-data:/data/db
    networks:
      - de-network

  redis:
    image: redis:7-alpine
    networks:
      - de-network

volumes:
  arch-data:

networks:
  de-network:
    driver: bridge

Monitoring

Health Check

bash

GET /health

Response:
{
  "status": "healthy",
  "uptime": 172800,
  "version": "2.1.0",
  "services": {
    "database": "connected",
    "redis": "connected",
    "socketio": "active",
    "mapbox": "healthy"
  },
  "stats": {
    "activeOrders": 1523,
    "activeVehicles": 342,
    "socketConnections": 4521
  }
}

Next Steps

LSP API Reference Workspace API Agents API Complete API Docs

de.arch - Core Architecture Server ​

Service Overview

Architecture Overview ​

Key Features ​

LSP Operations

Workspace Management

Agent Coordination

Client Services

Real-time Events

Mapbox Integration

Technology Stack ​

API Modules ​

1. LSP API ​

2. Workspace API ​

3. Agents API ​

4. Clients API ​

Data Models ​

Order/Shipment ​

Vehicle ​

Warehouse ​

Real-time Features ​

WebSocket Connection ​

Event Types ​

Configuration ​

Environment Variables ​

Usage Examples ​

Create Order ​

Track Order ​

Manage Fleet ​

Performance Optimization ​

Caching Strategy

Database Indexing

Connection Pooling

Rate Limiting

Deployment ​

Docker Compose ​

Monitoring ​

Health Check ​

Next Steps ​

de.arch - Core Architecture Server

Architecture Overview

Key Features

Technology Stack

API Modules

1. LSP API

2. Workspace API

3. Agents API

4. Clients API

Data Models

Order/Shipment

Vehicle

Warehouse

Real-time Features

WebSocket Connection

Event Types

Configuration

Environment Variables

Usage Examples

Create Order

Track Order

Manage Fleet

Performance Optimization

Deployment

Docker Compose

Monitoring

Health Check

Next Steps