Core Concepts

Understanding the fundamental concepts of De. will help you build better applications and make the most of the platform.

Platform Overview

De. is designed as a multi-tenant logistics coordination platform that connects various stakeholders through unified APIs and real-time services.

Key Principles

1. Multi-tenancy Every organization operates in its own isolated workspace with dedicated resources and data separation.

2. Service-Oriented Architecture The platform is composed of specialized services that work together but can be used independently.

3. Real-time First All operations support real-time updates through WebSocket and MQTT protocols.

4. Developer-Centric APIs and SDKs are designed for ease of integration with comprehensive documentation and examples.

Workspaces

A workspace is the top-level organizational unit in De. Each workspace represents a business or organization using the platform.

Workspace Features

• Isolated Data - Each workspace has its own database and resources
• Access Control - Role-based permissions for users and API keys
• Billing & Subscriptions - Independent billing and usage tracking
• Service Providers - Connect LSPs, CSPs, and IoT providers
• Multi-region Support - Deploy across different geographic regions

Workspace Types

Development Workspace

• Testing and development environment
• Sandbox mode with limited resources
• Free or low-cost tier
• Full API access

Production Workspace

• Live application deployment
• High-availability infrastructure
• Production-grade security
• SLA guarantees

Service Providers

De. supports different types of service providers, each with specific roles in the logistics ecosystem.

Logistics Service Provider (LSP)

Organizations that provide transportation and delivery services.

Capabilities:

• Fleet management (vehicles, drivers, maintenance)
• Warehouse operations (inventory, inbound, fulfillment)
• Route optimization and dispatch
• Pricing and billing
• Real-time tracking

Use Cases:

• Last-mile delivery companies
• Freight forwarders
• 3PL/4PL providers
• Courier services

Commerce Service Provider (CSP)

Businesses that sell products and need delivery coordination.

Capabilities:

• Order management
• Multi-carrier integration
• Delivery options at checkout
• Customer tracking experience
• Returns management

Use Cases:

• E-commerce platforms
• Retail chains
• Marketplaces
• Direct-to-consumer brands

IoT Service Provider (IoTSP)

Organizations managing connected devices for tracking and monitoring.

Capabilities:

• Device registration and provisioning
• Real-time telemetry streaming
• Command and control
• Alert management
• Data analytics

Use Cases:

• GPS tracking devices
• Temperature sensors
• Smart locks
• Fleet telematics

Developer (DEV)

Software teams building logistics-enabled applications.

Capabilities:

• Full API access
• SDK integration
• Custom plugin development
• Webhook integrations
• Testing environments

Use Cases:

• Custom logistics platforms
• Mobile applications
• Integration middleware
• Analytics dashboards

Authentication & Authorization

Access Tokens

De. uses JWT-based access tokens for API authentication.

Token Types:

• User Tokens - Issued after user authentication
• API Keys - Long-lived tokens for server-to-server communication
• Service Tokens - Scoped tokens for specific operations

Authentication Flows

Phone Authentication

1. User enters phone number
2. System sends SMS verification code
3. User submits code
4. System issues access token

Email/Password Authentication

1. User provides email and password
2. System validates credentials
3. System issues access token

OAuth/SSO

1. User initiates OAuth flow
2. Third-party provider authenticates
3. System receives authorization
4. System issues access token

Authorization Model

Role-Based Access Control (RBAC)

Each user has roles that determine their permissions:

• Owner - Full workspace control
• Admin - User and resource management
• Developer - API access and integration
• Operator - Day-to-day operations
• Viewer - Read-only access

Permission Scopes

API tokens can be scoped to specific operations:

workspace:read
workspace:write
orders:read
orders:write
fleet:manage
devices:control

Data Models

Hierarchical Structure

Workspace
├── Users (Admins, Operators, Developers)
├── Service Providers (LSPs, CSPs, IoTSPs)
├── Resources
│   ├── Fleets (Vehicles, Drivers)
│   ├── Warehouses (Inventory, Zones)
│   ├── Devices (GPS, Sensors)
│   └── Orders (Shipments, Deliveries)
└── Configuration
    ├── Pricing Rules
    ├── Coverage Areas
    └── Integration Settings

Key Entities

Order/Shipment

• Represents a delivery request
• Contains pickup and delivery locations
• Tracks packages and waypoints
• Manages status lifecycle

Vehicle

• Represents a delivery vehicle
• Tracks location in real-time
• Maintains service history
• Manages capacity and availability

Warehouse

• Physical storage location
• Manages inventory levels
• Processes inbound/outbound
• Coordinates fulfillment

Device

• IoT hardware unit
• Streams telemetry data
• Receives commands
• Reports status and alerts

Real-time Communication

WebSocket (Socket.IO)

Used for bidirectional real-time communication between clients and servers.

Use Cases:

• Live order status updates
• Driver location tracking
• Notification delivery
• Event streaming

Connection Flow:

import io from 'socket.io-client'

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

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

MQTT

Industry-standard protocol for IoT device communication.

Use Cases:

• GPS tracker telemetry
• Sensor data streaming
• Device commands
• Alert notifications

Topic Structure:

{workspace_id}/devices/{device_id}/telemetry
{workspace_id}/devices/{device_id}/commands
{workspace_id}/devices/{device_id}/status

API Versioning

De. APIs use URL-based versioning to maintain backward compatibility.

Version Format

https://api.dedot.io/v1/orders
https://api.dedot.io/v2/orders

Deprecation Policy

• New versions announced 6 months in advance
• Old versions supported for 12 months after deprecation
• Migration guides provided for breaking changes
• Gradual rollout with opt-in beta access

Version Selection

Recommended: Use the latest stable version for new projects.

Migration: Test thoroughly in development workspace before upgrading production.

Environment Management

Environment Types

Development (dev)

• Local development and testing
• Sandbox data
• No rate limits
• Full debugging enabled

Staging (staging)

• Pre-production testing
• Production-like configuration
• Isolated from live data
• Performance testing enabled

Production (prod)

• Live customer traffic
• High availability
• Strict security
• Monitoring and alerts

Configuration

Different environments can have different settings:

const config = {
  dev: {
    apiUrl: 'https://dev-api.dedot.io',
    msiUrl: 'https://dev-map.dedot.io'
  },
  staging: {
    apiUrl: 'https://staging-api.dedot.io',
    msiUrl: 'https://staging-map.dedot.io'
  },
  prod: {
    apiUrl: 'https://api.dedot.io',
    msiUrl: 'https://map.dedot.io'
  }
}

Event-Driven Architecture

De. uses events to coordinate actions across services.

Event Types

System Events

• workspace.created
• user.registered
• service.connected

Order Events

• order.created
• order.assigned
• order.in_transit
• order.delivered
• order.cancelled

Fleet Events

• vehicle.location_updated
• vehicle.maintenance_due
• driver.shift_started

IoT Events

• device.connected
• device.telemetry
• device.alert
• device.offline

Event Subscription

Subscribe to events via webhooks or WebSocket connections:

Webhooks:

{
  "url": "https://your-app.com/webhooks/de",
  "events": ["order.created", "order.delivered"],
  "secret": "webhook-signing-secret"
}

WebSocket:

socket.on('order:*', (event, data) => {
  console.log(`Order event: ${event}`, data)
})

Rate Limiting

API requests are subject to rate limits based on workspace tier.

Default Limits

Tier	Requests/minute	Burst
Free	60	10
Starter	300	30
Professional	1,000	100
Enterprise	Custom	Custom

Rate Limit Headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

Best Practices

• Implement exponential backoff for retries
• Cache responses when appropriate
• Use webhooks instead of polling
• Batch requests when possible
• Monitor rate limit headers

Error Handling

De. uses standard HTTP status codes and structured error responses.

Error Response Format

{
  "error": true,
  "status": "ERROR_CODE",
  "message": "Human-readable error message",
  "details": {
    "field": "Additional context"
  }
}

Common Error Codes

Status	Code	Meaning
400	INVALID_REQUEST	Malformed request or validation error
401	UNAUTHORIZED	Missing or invalid authentication
403	FORBIDDEN	Insufficient permissions
404	NOT_FOUND	Resource does not exist
429	RATE_LIMITED	Too many requests
500	INTERNAL_ERROR	Server error
503	SERVICE_UNAVAILABLE	Temporary outage

Error Handling Strategy

try {
  const response = await access.request({
    url: '/orders',
    method: 'POST',
    body: orderData
  })
} catch (error) {
  if (error.status === 401) {
    // Refresh token or re-authenticate
  } else if (error.status === 429) {
    // Implement backoff and retry
  } else {
    // Log error and show user-friendly message
  }
}

Next Steps

Now that you understand the core concepts:

• Learn about platform architecture
• Install and configure De.
• Setup authentication
• Build your first app
• Review best practices