O2O - Software Requirement Specifications

Logistics Seal & Container Tracking Platform


Version: 1.0

Date: 27-03-2026

Classification: Confidential


Table of Contents


  1. Project Overview
  2. Functional Requirements
  3. Software Architecture
  4. System Flows


1. Project Overview


A B2B SaaS platform that enables end-to-end logistics tracking of containerized cargo across multi-modal transportation (road → vessel → road), integrated with government-approved bolt seal vendor Sepio Products, and a third-party vessel tracking provider. The platform serves insurance and compliance purposes by maintaining an auditable record of container integrity throughout transit.


Key Actors:

  • System User — Internal staff/admin managing the platform
  • Customer — The cargo owner (exporter/transporter)
  • Sepio — Government-approved seal vendor (API integration)
  • Vessel Tracking Vendor — Third-party container tracking API (private vendor)
  • Customs Officer — External party verifying seals at ports (no direct platform access)


2. Functional Requirements


2.1 Customer Management (System User)


  • System users can create a customer record with: name, email, and mobile number.
  • On creation, the platform auto-sends an email with login credentials to the customer.
  • System users can view, edit, and deactivate customer accounts.


2.2 Customer Onboarding


  • Customer logs into the portal or mobile/desktop application using emailed credentials.

  • Customer completes a multi-step onboarding form capturing:

    • Personal details (name, designation)
    • Company details (company name, address, GST number)
    • KYC/compliance fields required by Sepio
  • On form submission, the platform calls the Sepio Customer Onboarding API with all collected details.
  • Sepio triggers an OTP to the customer's registered mobile/email.
  • Customer enters the OTP on the platform.
  • Platform calls the Sepio OTP Verification API.
  • On successful verification, onboarding is marked complete.
  • Customer has no direct interaction with Sepio; all Sepio communication is proxied through the platform.


2.3 Seal & Rate Management (System User)


  • System users define seal pricing per customer, using quantity-based tiered pricing (e.g., 1–50 seals = ₹X/seal, 51–200 = ₹Y/seal).
  • Pricing tiers and quantities are configurable per customer.
  • Rates set by system users are independent of the organization's purchase cost from Sepio (margin is internal).


2.4 Seal Ordering (Customer)


  • Customer navigates to the order page and enters a desired seal quantity.
  • Platform displays the applicable per-seal price dynamically based on quantity tiers.
  • Platform shows a pre-order invoice summary (quantity, unit price, total).
  • Customer confirms and places the order. No online payment is processed; payment is cash/offline.
  • On order placement, the platform calls the Sepio Seal Order API (customer identity + quantity).
  • Sepio returns unique seal numbers for each seal ordered.
  • Platform stores seal records (seal number, status: unassigned) linked to the customer.
  • Sepio ships seals to the customer's address (stored during onboarding). Platform does not manage physical delivery.
  • Platform displays Sepio shipment tracking for the seal delivery order via Sepio's tracking APIs.


2.5 Trip Creation (Customer)


  • Customer creates a trip for a container, providing:

    • Vehicle registration number
    • Driver info: name, driving license number, Aadhaar number, phone number
    • Container number
    • Bolt seal selection (from customer's available/unassigned seals)
    • eWay Bill
    • e-Invoice
    • Declared cargo value
    • Dispatch location (address, pincode, lat/long)
    • Delivery location (address, pincode, lat/long)
    • Origin Port / Airport
    • Destination Port / Airport
    • Dispatch date
    • ePOD Reference (ePODR)
  • Selected seal is mapped to the trip and its status changes to in-use.
  • Platform notifies Sepio via API that the seal (by seal number) is assigned to this trip, enabling customs verification at ports.


2.6 Seal Verification & Status Monitoring


  • At origin and destination ports, customs officers verify seals directly with Sepio (no platform involvement in this step).
  • Sepio APIs provide seal status (valid, tampered, broken, etc.).
  • Platform polls or webhooks Sepio Seal Status API and displays current seal status on the trip detail page.
  • Seal status does not block the trip from progressing; it is informational for the customer and insurance record.


2.7 Vessel & Container Tracking (Customer)


  • After the container is loaded onto a vessel, the customer's staff updates the trip with vessel information (vessel name, voyage number, or relevant identifiers).
  • Platform calls the Vessel Tracking Vendor API using vessel/container details.
  • Platform displays live container position, route history, and ETA from port to destination port.
  • When the container departs the destination port, the Vessel Tracking API signals departure; the platform marks the vessel leg as complete and tracking ends.


2.8 Destination Confirmation (Customer)


  • After the container leaves the destination port, no automated tracking is available.
  • Customer's staff manually updates the trip with final delivery confirmation details.
  • On submission, trip status changes to Completed.
  • All trip data is locked for record/audit purposes.


2.9 Trip Dashboard & History


  • Customers can view all trips with statuses: Draft, In Transit, At Port, On Vessel, Delivered, Completed.
  • System users can view all trips across all customers with filter/search by date, customer, status, seal number.
  • Full trip audit trail is stored and viewable.


5. Software Architecture


Architecture Pattern

3-Tier Web Application with a decoupled frontend, RESTful backend API, and a relational database. Third-party integrations are isolated behind an internal adapter/service layer. Both the web portal and mobile/desktop applications consume the same backend API.


┌───────────────────────────────────────────────────────────────────┐
│                              Clients                              │
│   Web Portal         Mobile App           Desktop App             │
│  (System User /     (Customer)           (Customer)               │
│   Customer)                                                       │
└──────────┬──────────────────┬──────────────────┬──────────────────┘
           │                  │                  │
           └──────────────────▼──────────────────┘
                              │ HTTPS / REST
                              ▼
┌───────────────────────────────────────────────────────────────────┐
│                       Backend API (Node.js)                       │
│                                                                   │
│  ┌────────────┐  ┌────────────┐  ┌────────────────────┐           │
│  │  Auth      │  │  Customer  │  │  Trip Management   │           │
│  │  Module    │  │  Module    │  │  Module            │           │
│  └────────────┘  └────────────┘  └────────────────────┘           │
│  ┌────────────┐  ┌────────────┐  ┌────────────────────┐           │
│  │  Seal &    │  │  Order     │  │  Notifications     │           │
│  │  Rate Mgmt │  │  Module    │  │  Module            │           │
│  └────────────┘  └────────────┘  └────────────────────┘           │
│                                                                   │
│  ┌─────────────────────────────────────────────────────────────┐  │
│  │                  Third-Party Adapter Layer                  │  │
│  │   ┌──────────────────┐      ┌──────────────────────────┐    │  │
│  │   │  Sepio Adapter   │      │  Vessel Tracking Adapter │    │  │
│  │   └──────────────────┘      └──────────────────────────┘    │  │
│  └───────────────────────────────────────────────────────── ───┘  │
└──────────────────────────────┬────────────────────────────────────┘
                               │
               ┌───────────────┴──────────────────┐
               ▼                                  ▼
┌──────────────────────────┐      ┌─────────────────────────────────┐
│      PostgreSQL DB       │      │         External APIs           │
│      (Primary Store)     │      │   - Sepio APIs                  │
└──────────────────────────┘      │   - Vessel Tracking API         │
                                  │   - Email Service (SMTP/SES)    │
                                  └─────────────────────────────────┘


Key Design Decisions


  • Adapter Pattern for all third-party APIs: Sepio and Vessel Tracker are accessed only through internal adapter classes, making them swappable without touching business logic.
  • Single API for all clients: The web portal, mobile app, and desktop app all consume the same RESTful backend API, ensuring consistency and a single source of truth.
  • Event/Status Log Table: Every state change on a trip or seal is appended to an immutable event log (not overwritten) for audit compliance.
  • Background Jobs: Seal delivery status polling and vessel position polling run as background cron jobs, not on-request, to avoid blocking user interactions.
  • No Payment Gateway: Explicitly out of scope. Order records store only quantity, rate, and amount for invoice display.


6. System Flows


Flow 1: Customer Creation & Invitation

System User fills customer form
  → Platform creates Customer record (status: Pending)
  → Platform sends welcome email with login credentials
  → Customer receives email


Flow 2: Customer Onboarding

Customer logs in via web portal or application
  → Completes onboarding form (company, GST, KYC fields)
  → Platform calls Sepio Onboarding API (passes customer data)
  → Sepio sends OTP to customer mobile/email
  → Customer enters OTP on platform
  → Platform calls Sepio OTP Verification API
  → On success → Customer status: Active / Onboarded


Flow 3: Seal Ordering

Customer enters desired quantity
  → Platform calculates price from tiered rate config
  → Customer reviews invoice summary and confirms
  → Platform calls Sepio Order API (customer ID, quantity)
  → Sepio returns [seal_number_1, seal_number_2, ...]
  → Platform stores seals (status: Unassigned)
  → Customer views Sepio shipment tracking on portal or application


Flow 4: Trip Creation & Seal Assignment

Customer fills trip form (vehicle, driver, container, cargo, locations)
  → Customer selects an Unassigned seal from their inventory
  → Platform creates Trip record (status: In Transit)
  → Seal status updated to: In Use
  → Platform calls Sepio Seal Assignment API (seal number + trip metadata)
  → Sepio registers seal as active for customs validation


Flow 5: Seal Status Monitoring

[Background Job]
  → Platform polls Sepio Seal Status API for all active seals
  → Updates seal_status on trip (Valid / Tampered / Broken / Unknown)
  → Customer views status on Trip Detail page via web or application (informational only)


Flow 6: Vessel Tracking

Customer's staff adds vessel information to the trip (via web or application)
  → Platform calls Vessel Tracking API (container/vessel identifiers)
  → [Background Job] polls Vessel API for position updates
  → Platform displays route, current position, ETA
  → On container departure from destination port:
      → Platform marks vessel leg as Complete
      → Tracking stops


Flow 7: Destination Confirmation (Manual)

Customer's staff opens trip on portal or application
  → Submits final delivery confirmation (date, receiving party, notes)
  → Trip status → Completed
  → All trip data locked (read-only)


End of Document