MDL Blind Shipping Calculator - Process Architecture

This document outlines the business logic and technical workflows of the application using BPMN-style modeling (via Mermaid).

1. End-To-End Quote Generation Process

graph TD
    %% Start Event
    Start((User Access Request)) --> AuthCheck{Authenticated?}

    %% Auth Flow
    AuthCheck -- No --> AzureAD[Azure AD Login / MFA]
    AzureAD --> Landing
    AuthCheck -- Yes --> Landing[App Dashboard]

    %% Main Branching
    Landing --> ManageDir[Manage Directory]
    Landing --> ManageHubs[Manage Hubs]
    Landing --> StartCalc[Start Calculation]

    %% Data Extraction Workflow
    subgraph "Data Intake & AI Parsing"
        ManageDir --> Upload[Upload PDF/Image/Link]
        Upload --> Processing{Process Type}
        Processing -- "Invoice/PO" --> OCR[Tesseract OCR / PDF Text]
        OCR --> InvoiceAI[Invoice Parser Logic]
        Processing -- "Spec Sheet" --> SpecAI[Gemini 1.5 'Magic Lookup']
        InvoiceAI --> Review[User Validation Screen]
        SpecAI --> Review
        Review --> DB[(Supabase Persistence)]
    end

    %% Calculation Workflow
    subgraph "Shipping Quote Engine"
        StartCalc --> SelectEntities[Select Supplier & Customer]
        SelectEntities --> SelectProduct[Select Product or Manual Dims]
        SelectProduct --> OriginCheck{Supplier Intl?}

        %% Leg 1 Logic
        OriginCheck -- Yes --> SelectHub[Select Intermediate Hub]
        SelectHub --> Leg1[Fetch Leg 1: Supplier to Hub]
        Leg1 --> HubLeg[Fetch Leg 2: Hub to Customer]

        %% Direct Leg
        OriginCheck -- No --> DirectLeg[Fetch Direct: Supplier to Customer]

        %% Customs Logic
        HubLeg --> CrossBorder{Cross-Border?}
        DirectLeg --> CrossBorder
        CrossBorder -- Yes --> Customs[Apply Customs Fee $175]
        CrossBorder -- No --> Finance
        Customs --> Finance[Currency & Margin %]
    end

    %% Conclusion
    Finance --> FinalQuote[Display Final Client Quote]
    FinalQuote --> End((Quote Delivered))

    %% Styling
    style Start fill:#f9f,stroke:#333,stroke-width:2px
    style End fill:#f9f,stroke:#333,stroke-width:2px
    style AzureAD fill:#def,stroke:#44a
    style DB fill:#ff9,stroke:#990,stroke-dasharray: 5 5
    style Prices fill:#dff,stroke:#099

2. Technical Component Interaction

sequenceDiagram
    participant User
    participant NextJS as Next.js (App Router)
    participant AI as Gemini 1.5 Flash
    participant DB as Supabase
    participant Ship as TotalShip API

    User->>NextJS: Uploads Spec Sheet
    NextJS->>AI: Extracts JSON (Name, Wgt, Dims)
    AI-->>NextJS: Returns Structured Data
    NextJS->>User: Shows Preview
    User->>NextJS: Confirms & Saves
    NextJS->>DB: POST /products

    User->>NextJS: Starts Calculation
    NextJS->>DB: GET /suppliers & /customers
    NextJS->>Ship: XML POST (Origin/Dest/Dims)
    Ship-->>NextJS: Returns Multi-Carrier Rates
    NextJS->>NextJS: Computes Margin & Exchange
    NextJS-->>User: Visual Quote Card

3. Data Flow Entities