Platform Architecture

De. is built as a distributed, multi-tenant platform with specialized services that work together to provide comprehensive logistics coordination capabilities.

High-Level Overview

┌─────────────────────────────────────────────────────────────────┐
│                         De. Ecosystem                            │
├─────────────────────────────────────────────────────────────────┤
│                                                                   │
│  ┌──────────────┐  ┌──────────────┐  ┌─────────────────────┐   │
│  │   de.auth    │  │   de.arch    │  │      de.iotb        │   │
│  │ Authentication│  │  Core APIs   │  │  IoT Platform       │   │
│  │   & Users    │  │  & Services  │  │  MQTT & Devices     │   │
│  └──────┬───────┘  └──────┬───────┘  └──────────┬──────────┘   │
│         │                  │                      │              │
│         └──────────────────┴──────────────────────┘              │
│                            │                                     │
│                ┌───────────┴──────────┐                          │
│                │                      │                          │
│         ┌──────────────┐      ┌─────────────┐                   │
│         │   de.eui     │      │   de.sdk    │                   │
│         │ Embeddable   │◄─────┤  Web SDK    │                   │
│         │ Map UI       │      └─────────────┘                   │
│         └──────────────┘              │                          │
│                                ┌──────────────┐                  │
│                                │  de.sdk-rn   │                  │
│                                │ React Native │                  │
│                                │     SDK      │                  │
│                                └──────────────┘                  │
│                                                                   │
└─────────────────────────────────────────────────────────────────┘

Backend Services

de.auth - Authentication Service

Central authentication and user management service for the entire platform.

Technology Stack:

Fastify (Web framework)
MongoDB (User database)
JWT (Token generation)
AWS SDK (File storage)

Responsibilities:

User registration and authentication
Multi-channel auth (phone, email, OAuth)
Session management
Profile management
Access token generation
File uploads (avatars, documents)

API Endpoints:

POST   /auth/signin          - Initiate authentication
POST   /auth/verify          - Verify authentication code
POST   /auth/signout         - End session
GET    /user                 - Get user profile
PATCH  /user/profile         - Update profile
POST   /utilities/upload     - Upload files

Data Model:

User
├── profile (firstName, lastName, phone, email, photo)
├── account (uid, types, workspace)
├── connection (tokens, sessions)
└── settings (preferences, notifications)

de.arch - Core Architecture Server

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

Technology Stack:

Fastify (Web framework)
MongoDB (Primary database)
Socket.IO (Real-time communication)
Redis (Caching and pub/sub)
Mapbox SDK (Location services)

Responsibilities:

Logistics operations (LSP API)
Workspace management
Agent coordination
Client operations
Service provider integrations
Real-time event distribution

API Modules:

LSP (Logistics Service Provider) API

Fleet Management:
  /lsp/fleets/vehicles
  /lsp/fleets/maintenance
  /lsp/fleets/parking

Warehouse Operations:
  /lsp/warehouses
  /lsp/inventory
  /lsp/inbound
  /lsp/hubs

Pricing Engine:
  /lsp/pricing/contracts
  /lsp/pricing/templates
  /lsp/pricing/tiers
  /lsp/pricing/adjustments

Operations:
  /lsp/coverage
  /lsp/carriers
  /lsp/shipments
  /lsp/slots
  /lsp/reports

Workspace API

/workspace/access         - Access control
/workspace/admins         - Admin management
/workspace/billings       - Billing and invoices
/workspace/connectors     - Service integrations
/workspace/subscriptions  - Subscription management

Agent API

/agents/navigation        - Real-time routing
/agents/rides             - Ride management
/agents/shippings         - Delivery tasks

Client API

/clients/orders           - Order placement
/clients/preferences      - Delivery preferences
/clients/tracking         - Status updates

Data Flow:

Client Request
    ↓
API Gateway (Fastify)
    ↓
Authentication Middleware
    ↓
Business Logic Layer
    ↓
┌────────────┬────────────┬────────────┐
│  MongoDB   │   Redis    │  Socket.IO │
│  (Storage) │  (Cache)   │  (Events)  │
└────────────┴────────────┴────────────┘
    ↓
Response + Real-time Updates

de.iotb - IoT Backend Platform

Multi-tenant IoT platform for device connectivity, data streaming, and container orchestration.

Technology Stack:

Node.js/Bun (Runtime)
MongoDB (Device and telemetry data)
MQTT Broker (Device communication)
Socket.IO (Client updates)
AWS SDK (File storage)

Responsibilities:

MQTT broker management
Device registration and provisioning
Telemetry data collection
Command and control
Container orchestration
Event processing

Architecture Components:

Container Orchestration:

Control Panel
├── ORC (Orchestrator)
│   ├── Deploy shared containers
│   ├── Deploy standalone containers
│   └── Manage container lifecycle
├── OPD (Operation Databases)
│   ├── Workspace DB
│   └── IoT DB
├── IOS (IoT Socket Server)
│   └── Client WebSocket connections
└── MCS (Managed Containers)
    ├── Shared resources
    └── Standalone resources

Container Types:

Shared Container (Multi-tenant)

Shared database instance
Shared file storage
Shared MQTT channels
Lower cost
Suitable for small workloads

Standalone Container (Dedicated)

Isolated database
Dedicated file storage
Private MQTT broker
Higher performance
Required for compliance

Resource Management:

Container
├── Database (MongoDB instance)
├── FileStorage (S3/Spaces bucket)
├── Channel (MQTT client)
└── ActiveRules (Automation engine)

MQTT Topic Structure:

{workspace_id}/devices/{device_id}/telemetry/location
{workspace_id}/devices/{device_id}/telemetry/sensors
{workspace_id}/devices/{device_id}/commands/config
{workspace_id}/devices/{device_id}/status/online

Event Processing Flow:

Device (MQTT)
    ↓
MQTT Broker
    ↓
Event Manager
    ↓
┌──────────┬──────────┬──────────┐
│  Rules   │  Storage │  Forward │
│  Engine  │  (DB)    │  (Socket)│
└──────────┴──────────┴──────────┘
    ↓
Actions & Notifications

Frontend Services

de.eui - Embeddable User Interface

Web-based map interface that can be embedded into any application via iframe.

Technology Stack:

Vite (Build tool)
Mapbox GL JS / Google Maps (Map rendering)
Fastify (Server component)
iframe.io (Cross-origin communication)

Architecture:

Parent Application
    ↓
iframe.io Bridge
    ↓
de.eui (Embedded)
    ↓
┌─────────────┬─────────────┐
│  Map Engine │  Control    │
│  (Mapbox)   │  Board      │
└─────────────┴─────────────┘
    ↓
Map Display + Interactions

Communication Protocol:

typescript

// Parent app sends message
msi.controls.setRoute({ origin, destination })

// Bridge translates
iframeBridge.send('controls:setRoute', { origin, destination })

// de.eui receives and executes
mapEngine.drawRoute(origin, destination)

// de.eui sends response
iframeBridge.respond('controls:setRoute:success', { routeId })

SDKs

de.sdk - Web SDK

Complete JavaScript/TypeScript SDK for web applications.

Module Structure:

@de./sdk
├── MSI (Map Service Interface)
│   ├── Controls (Promise-based API)
│   ├── Handles (Stream-based API)
│   └── Plugins (Extension system)
├── DClient (Client operations)
│   ├── Order (Order management)
│   ├── Event (Event subscriptions)
│   └── Client (Customer operations)
├── Access (Authentication & HTTP)
└── Utils (Helper functions)

Communication Flow:

Application Code
    ↓
de.sdk API
    ↓
┌──────────────┬──────────────┐
│  iframe.io   │  Socket.IO   │
│  (MSI)       │  (Events)    │
└──────────────┴──────────────┘
    ↓           ↓
  de.eui    de.arch

de.sdk-rn - React Native SDK

Mobile SDK for iOS and Android applications.

Components:

@de./sdk-rn
├── MSI (Mobile map interface)
│   └── WebView + Bridge
├── DClient (Mobile operations)
└── Native Modules
    ├── Location Services
    ├── Background Tracking
    └── Push Notifications

Mobile Architecture:

React Native App
    ↓
SDK Components
    ↓
┌──────────────┬──────────────┐
│  WebView     │  Native      │
│  (MSI)       │  Modules     │
└──────────────┴──────────────┘
    ↓           ↓
  de.eui    Platform APIs

Communication Patterns

HTTP REST

Synchronous request-response for CRUD operations.

Pattern:

Client → HTTP Request → Server
Client ← HTTP Response ← Server

Use Cases:

Create orders
Update profiles
Query data
Configuration

WebSocket (Socket.IO)

Bidirectional real-time communication.

Pattern:

Client ⇄ WebSocket Connection ⇄ Server

Use Cases:

Order status updates
Live location tracking
Notifications
Chat/messaging

Event Flow:

Server Event
    ↓
Redis Pub/Sub
    ↓
Socket.IO Adapter
    ↓
Connected Clients

MQTT

Lightweight pub/sub protocol for IoT devices.

Pattern:

Device → MQTT Publish → Broker → MQTT Subscribe → Server

Use Cases:

GPS telemetry
Sensor data
Device commands
Status updates

Quality of Service (QoS):

QoS 0: At most once (fire and forget)
QoS 1: At least once (acknowledged)
QoS 2: Exactly once (guaranteed)

Webhooks

HTTP callbacks for event notifications.

Pattern:

Server Event → HTTP POST → Client Webhook URL

Use Cases:

Order created/updated
Payment processed
Delivery completed
Device alert

Data Storage

MongoDB

Primary database for all services.

Collections per Service:

de.auth:

users - User accounts and profiles
auth - Authentication sessions
tokens - Access tokens

de.arch:

workspaces - Workspace configurations
orders - Orders and shipments
vehicles - Fleet vehicles
warehouses - Warehouse locations
inventory - Stock levels
pricing - Pricing rules

de.iotb:

devices - Device registry
telemetry - Time-series data
containers - Container metadata
rules - Automation rules

Indexing Strategy:

Geospatial indexes for location queries
Compound indexes for common query patterns
TTL indexes for expiring data
Text indexes for search

Redis

In-memory data store for caching and pub/sub.

Use Cases:

Session caching
API response caching
Rate limiting counters
Real-time event distribution
Job queues

Data Structures:

Strings: Cache values
Hashes: Session data
Sets: Rate limit tracking
Sorted Sets: Leaderboards
Pub/Sub: Event distribution

S3/Spaces (Object Storage)

File storage for user uploads and assets.

Storage Structure:

de-storage/
├── avatars/
│   └── {userId}/{filename}
├── documents/
│   └── {workspaceId}/{documentId}
└── uploads/
    └── {workspaceId}/{uploadId}

Security Architecture

Authentication Flow

1. Client Request
   ↓
2. Extract Token
   ↓
3. Verify JWT Signature
   ↓
4. Check Token Expiry
   ↓
5. Load User Context
   ↓
6. Verify Permissions
   ↓
7. Process Request

Authorization Layers

Level 1: Workspace Isolation

Each request scoped to workspace
Data queries filtered by workspace_id
Cross-workspace access prohibited

Level 2: Role-Based Access

User roles checked against resource
Operation permissions validated
Scope restrictions enforced

Level 3: Resource Ownership

User ownership verified
Team membership checked
Share permissions validated

Data Encryption

At Rest:

Database encryption (MongoDB)
File encryption (S3 server-side)
Backup encryption

In Transit:

TLS 1.3 for all connections
Certificate pinning (mobile)
Secure WebSocket (WSS)
MQTTS for IoT devices

API Security

Rate Limiting:

Per-IP: 100 requests/minute
Per-Token: Based on tier
Burst: 2x normal limit

Request Validation:

Schema validation (JSON Schema)
Input sanitization
SQL injection prevention
XSS protection

CORS Policy:

typescript

{
  origin: allowedOrigins,
  credentials: true,
  methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'],
  allowedHeaders: ['Authorization', 'Content-Type']
}

Scalability

Horizontal Scaling

Stateless Services:

de.auth (multiple instances)
de.arch (load balanced)
de.eui (CDN distributed)

Stateful Services:

MongoDB (replica sets)
Redis (cluster mode)
MQTT Broker (federation)

Load Balancing

Client Requests
    ↓
Load Balancer (Nginx/HAProxy)
    ↓
┌─────────┬─────────┬─────────┐
│ Node 1  │ Node 2  │ Node 3  │
└─────────┴─────────┴─────────┘
    ↓
Shared Database & Cache

Caching Strategy

L1 Cache (Application):

In-memory for hot data
TTL: 1-5 minutes
Size: Limited by RAM

L2 Cache (Redis):

Distributed cache
TTL: 5-60 minutes
Eviction: LRU policy

L3 Cache (CDN):

Static assets
TTL: Hours to days
Edge locations

Database Optimization

Read Replicas:

Primary: Write operations
Secondaries: Read operations
Automatic failover

Sharding:

Shard key: workspace_id
Range-based distribution
Even load distribution

Monitoring & Observability

Metrics

System Metrics:

CPU, Memory, Disk usage
Network throughput
Request latency
Error rates

Business Metrics:

Orders per second
Active devices
API usage
User activity

Logging

Structured Logging:

json

{
  "timestamp": "2024-01-16T09:00:00Z",
  "level": "info",
  "service": "de.arch",
  "traceId": "abc123",
  "userId": "user_456",
  "action": "order.created",
  "duration": 125,
  "metadata": {}
}

Log Aggregation:

Services → Fluentd → Elasticsearch → Kibana

Tracing

Distributed Tracing:

Client Request (trace_id: abc123)
    ↓ span_1
de.auth (verify token)
    ↓ span_2
de.arch (create order)
    ↓ span_3
MongoDB (insert)
    ↓ span_4
Redis (cache)
    ↓ span_5
Socket.IO (notify)

Alerting

Alert Conditions:

Error rate > 1%
Latency > 1 second
CPU > 80%
Disk > 90%
Service downtime

Notification Channels:

PagerDuty (critical)
Slack (warnings)
Email (info)

Disaster Recovery

Backup Strategy

Databases:

Continuous replication
Daily snapshots
Weekly archives
30-day retention

Files:

Multi-region replication
Versioning enabled
90-day retention

Recovery Procedures

RTO (Recovery Time Objective): < 1 hour RPO (Recovery Point Objective): < 5 minutes

Failover Process:

1. Detect failure
2. Promote secondary
3. Update DNS
4. Verify services
5. Monitor recovery

Platform Architecture ​

High-Level Overview ​

Backend Services ​

de.auth - Authentication Service ​

de.arch - Core Architecture Server ​

de.iotb - IoT Backend Platform ​

Frontend Services ​

de.eui - Embeddable User Interface ​

SDKs ​

de.sdk - Web SDK ​

de.sdk-rn - React Native SDK ​

Communication Patterns ​

HTTP REST ​

WebSocket (Socket.IO) ​

MQTT ​

Webhooks ​

Data Storage ​

MongoDB ​

Redis ​

S3/Spaces (Object Storage) ​

Security Architecture ​

Authentication Flow ​

Authorization Layers ​

Data Encryption ​

API Security ​

Scalability ​

Horizontal Scaling ​

Load Balancing ​

Caching Strategy ​

Database Optimization ​

Monitoring & Observability ​

Metrics ​

Logging ​

Tracing ​

Alerting ​

Disaster Recovery ​

Backup Strategy ​

Recovery Procedures ​

Next Steps ​

Platform Architecture

High-Level Overview

Backend Services

de.auth - Authentication Service

de.arch - Core Architecture Server

de.iotb - IoT Backend Platform

Frontend Services

de.eui - Embeddable User Interface

SDKs

de.sdk - Web SDK

de.sdk-rn - React Native SDK

Communication Patterns

HTTP REST

WebSocket (Socket.IO)

MQTT

Webhooks

Data Storage

MongoDB

Redis

S3/Spaces (Object Storage)

Security Architecture

Authentication Flow

Authorization Layers

Data Encryption

API Security

Scalability

Horizontal Scaling

Load Balancing

Caching Strategy

Database Optimization

Monitoring & Observability

Metrics

Logging

Tracing

Alerting

Disaster Recovery

Backup Strategy

Recovery Procedures

Next Steps