Technical Architecture Document v1.0

PINAXIS System Architecture

Warehouse Data Analytics Platform with MCP Integration Layer, GEBHARDT Product Matching, and SAP EWM/MFS Bridge

Author: Digit2ai / RinglyPro Client: PINAXIS LLC / GEBHARDT Group Date: March 2026 Status: Production (v1.0)

Table of Contents

  1. System Overview & Purpose
  2. High-Level Architecture (6-Layer Model)
  3. MCP Integration Layer
  4. Data Model & Database Schema
  5. Data Ingestion Pipeline
  6. Analytics Engine (8 Computation Types)
  7. GEBHARDT Product Matching Engine
  8. SAP EWM/MFS Integration Bridge
  9. API Reference
  10. Dashboard Architecture
  11. PDF Report Generator
  12. Security & Authentication
  13. Deployment & Infrastructure
  14. Implementation Roadmap

1 System Overview & Purpose

What PINAXIS does and why it exists

PINAXIS is a warehouse data analytics platform that enables GEBHARDT Intralogistics Group's consulting arm (PINAXIS LLC) to:

  1. Accept warehouse data uploads (CSV/XLSX) from prospect customers — item master, inventory, goods-in, and goods-out datasets
  2. Automatically run 8 standardized analytics that PINAXIS currently performs manually — order structure, throughput, ABC classification, fit analysis
  3. Auto-match analysis results to the GEBHARDT product portfolio using a weighted multi-criteria scoring engine
  4. Generate branded PDF reports with charts, KPIs, and product recommendations
  5. Bridge into GEBHARDT's SAP EWM/MFS ecosystem via the RinglyPro MCP (Model Context Protocol) layer for CRM sync and downstream automation
8
Analytics Types
6
GEBHARDT Products
4
Data Sources
8
Database Tables
15+
API Endpoints
10
Dashboard Charts

Workflow

1
Upload
CSV/XLSX data files
2
Analyze
8 automated analytics
3
Match
GEBHARDT products
4
Report
PDF + dashboard
5
Sync
MCP → SAP/CRM

2 High-Level Architecture (6-Layer Model)

End-to-end system design from data input to operational output

PINAXIS System Architecture — 6-Layer Model
 ┌─────────────────────────────────────────────────────────────────────────────────┐
 │  LAYER 1: PROSPECT DATA INPUT                                                   │
 │  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐           │
 │  │ Item Master   │ │  Inventory   │ │  Goods-In    │ │  Goods-Out   │           │
 │  │ CSV / XLSX    │ │  CSV / XLSX  │ │  CSV / XLSX  │ │  CSV / XLSX  │           │
 │  │              │ │              │ │              │ │              │           │
 │  │ SKU, dims,   │ │ stock, bin,  │ │ receipt_id,  │ │ order_id,    │           │
 │  │ weight, UOM  │ │ location     │ │ supplier     │ │ ship_date    │           │
 │  └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘           │
 │         │                │                │                │                    │
 └─────────┼────────────────┼────────────────┼────────────────┼────────────────────┘
           │                │                │                │
           ▼                ▼                ▼                ▼
 ┌─────────────────────────────────────────────────────────────────────────────────┐
 │  LAYER 2: RINGLYPRO MCP SERVER  (Node.js / Express / PostgreSQL)                │
 │                                                                                 │
 │  ┌───────────────┐  ┌───────────────┐  ┌───────────────┐  ┌─────────────────┐  │
 │  │  Data Parser   │  │  Plausibility  │  │  Schema       │  │  Column Name    │  │
 │  │  CSV / XLSX    │──│  Validator     │──│  Normalizer   │──│  Alias Engine   │  │
 │  │  (xlsx lib)    │  │  (date range,  │  │  (type cast,  │  │  (DE/EN maps)   │  │
 │  │               │  │   row count)   │  │   null clean)  │  │                │  │
 │  └───────┬───────┘  └───────────────┘  └───────────────┘  └─────────────────┘  │
 │          │                                                                      │
 │          ▼                                                                      │
 │  ┌──────────────────────────────────────────────────────────────────────────┐   │
 │  │  PostgreSQL — 8 tables (pinaxis_ prefix)                                 │   │
 │  │  ┌─────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐   │   │
 │  │  │Projects │ │ Uploaded │ │ Item     │ │Inventory │ │  Goods In    │   │   │
 │  │  │         │ │ Files    │ │ Master   │ │ Data     │ │  Data        │   │   │
 │  │  └────┬────┘ └──────────┘ └──────────┘ └──────────┘ └──────────────┘   │   │
 │  │       │      ┌──────────┐ ┌──────────────┐ ┌──────────────────────┐    │   │
 │  │       └──────│Goods Out │ │ Analysis     │ │ Product              │    │   │
 │  │              │ Data     │ │ Results      │ │ Recommendations      │    │   │
 │  │              └──────────┘ └──────────────┘ └──────────────────────┘    │   │
 │  └──────────────────────────────────────────────────────────────────────────┘   │
 └────────────────────────────────────────┬────────────────────────────────────────┘
                                          │
                                          ▼
 ┌─────────────────────────────────────────────────────────────────────────────────┐
 │  LAYER 3: AI ANALYTICS ENGINE                                                   │
 │                                                                                 │
 │  ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐                  │
 │  │ Overview   │ │  Order     │ │ Order Time │ │ Throughput │                  │
 │  │ KPIs       │ │ Structure  │ │ Series     │ │ Monthly    │                  │
 │  └────────────┘ └────────────┘ └────────────┘ └────────────┘                  │
 │  ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐                  │
 │  │ Throughput │ │ Throughput │ │    ABC     │ │ Fit / No   │                  │
 │  │ Weekday    │ │ Hourly     │ │Classification│ │ Fit        │                  │
 │  └────────────┘ └────────────┘ └─────┬──────┘ └────────────┘                  │
 │                                      │ Gini coefficient                        │
 │                                      │ Lorenz curve                            │
 └──────────────────────────────────────┬──────────────────────────────────────────┘
                                        │
                                        ▼
 ┌─────────────────────────────────────────────────────────────────────────────────┐
 │  LAYER 4: GEBHARDT PRODUCT MATCHING ENGINE                                      │
 │                                                                                 │
 │  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐                           │
 │  │ StoreBiter   │ │ StoreBiter   │ │  InstaPick   │                           │
 │  │ MLS (Mini)   │ │ OLS (Over)   │ │  (G2P)       │                           │
 │  │ Score: 0-100 │ │ Score: 0-100 │ │ Score: 0-100 │                           │
 │  └──────────────┘ └──────────────┘ └──────────────┘                           │
 │  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐                           │
 │  │ ROTA-Sorter  │ │ Omnipallet   │ │  Versastore  │                           │
 │  │ (Sortation)  │ │ (Pallet)     │ │  (Flex Auto) │                           │
 │  │ Score: 0-100 │ │ Score: 0-100 │ │ Score: 0-100 │                           │
 │  └──────────────┘ └──────────────┘ └──────────────┘                           │
 │                                                                                 │
 │  Scoring: Multi-criteria weighted algorithm (5-6 factors per product)           │
 └──────────────────────────────────────┬──────────────────────────────────────────┘
                                        │
                                        ▼
 ┌─────────────────────────────────────────────────────────────────────────────────┐
 │  LAYER 5: OUTPUT & DELIVERY                                                     │
 │                                                                                 │
 │  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐          │
 │  │  React       │ │  PDF Report  │ │  REST API    │ │  MCP Sync    │          │
 │  │  Dashboard   │ │  (pdfmake)   │ │  (JSON)      │ │  (CRM Push)  │          │
 │  │  Recharts    │ │  40KB/report │ │  15+ routes  │ │  SAP / GHL   │          │
 │  └──────────────┘ └──────────────┘ └──────────────┘ └──────┬───────┘          │
 └─────────────────────────────────────────────────────────────┼──────────────────┘
                                                               │
                                                               ▼
 ┌─────────────────────────────────────────────────────────────────────────────────┐
 │  LAYER 6: GEBHARDT / PINAXIS OPERATIONS                                         │
 │                                                                                 │
 │  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐          │
 │  │ SAP EWM/MFS  │ │ Sales        │ │  Solution    │ │  Prospect    │          │
 │  │ CRM Pipeline │ │ Engineer     │ │  Architect   │ │  Customer    │          │
 │  │ Opportunity  │ │ Reviews      │ │  Validates   │ │  Receives    │          │
 │  │ Tracking     │ │ Recomm.      │ │  Config      │ │  Report      │          │
 │  └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘          │
 └─────────────────────────────────────────────────────────────────────────────────┘
Layer 1 — Prospect Data Input
CSV/XLSX uploads: Item Master (SKU, dimensions, weight), Inventory (stock, locations), Goods-In (deliveries), Goods-Out (sales orders). Plus business context via web form (shifts, growth, regulations).
Layer 2 — RinglyPro MCP Server
Node.js/Express application with data parser (xlsx + csv-parse), schema validation, column normalization (DE/EN), PostgreSQL storage (8 tables), and MCP proxy for CRM/SAP bridge.
Layer 3 — AI Analytics Engine
8 computation types using SQL aggregations: Overview KPIs, Order Structure, Order Time Series, Throughput (Monthly/Weekday/Hourly), ABC Classification with Gini coefficient, Fit/No-Fit bin analysis.
Layer 4 — GEBHARDT Product Matching
Multi-criteria weighted scoring (0-100) for 6 products: StoreBiter MLS, StoreBiter OLS, InstaPick, ROTA-Sorter, Omnipallet, Versastore. 5-6 factors per product with threshold/ideal bands.
Layer 5 — Output & Delivery
React + Recharts interactive dashboard, pdfmake PDF reports, REST API (JSON), MCP sync to SAP EWM/MFS and CRM systems.
Layer 6 — GEBHARDT Operations
Sales engineers review recommendations, solution architects validate configurations, prospects receive branded reports, opportunities tracked in SAP pipeline.

3 MCP Integration Layer

How PINAXIS connects to the RinglyPro Model Context Protocol ecosystem

PINAXIS operates as a self-contained MCP module within the RinglyPro platform. It follows the established pattern used by Store Health AI, TunjoRacing, and other modules — mounted as an Express sub-application at /pinaxis.

MCP Server Components

PINAXIS MCP Proxy

Data Analytics Proxy

Handles warehouse data upload, parsing, analytics orchestration, and product matching. Exposes RESTful endpoints under /pinaxis/api/v1/*.

Webhook Manager

Event Pipeline

HMAC-SHA256 verified webhook pipeline for receiving SAP Event Mesh events. Event deduplication prevents duplicate processing. Async architecture for scale.

AI Copilot

Natural Language Interface

Claude-powered natural language queries on analysis results. "What product fits this customer?" → retrieves analysis data and generates product recommendation.

Voice AI (Ana)

Multilingual Agent

ElevenLabs-powered voice agent trained on GEBHARDT product knowledge. Presents analysis findings via phone, qualifies leads, schedules follow-ups.

CRM Proxy

Zero Vendor Lock-in

Pattern-based proxy supporting SAP Sales Cloud, GoHighLevel, HubSpot, Zoho. PINAXIS results push to any connected CRM without code changes.

Workflow Engine

Multi-step Automation

Trigger-based execution: upload → parse → validate → analyze → match → report → sync. Context passing between steps with conditional branching.

MCP Data Flow

MCP Pipeline: Upload → Analyze → Match → Deliver
  Prospect          PINAXIS MCP         Analytics        Product          Delivery
  Customer          Server              Engine           Matcher          Layer
     │                  │                  │                │                │
     │  Upload CSV      │                  │                │                │
     │─────────────────>│                  │                │                │
     │                  │  Parse + Store   │                │                │
     │                  │─────────────────>│                │                │
     │                  │                  │  8 Analytics   │                │
     │                  │                  │───────────────>│                │
     │                  │                  │                │  Score 6       │
     │                  │                  │                │  Products      │
     │                  │                  │                │───────────────>│
     │                  │                  │                │                │ PDF Report
     │                  │                  │                │                │ Dashboard
     │                  │                  │                │                │ CRM Sync
     │  Download PDF    │                  │                │                │ Voice AI
     │<─────────────────────────────────────────────────────────────────────│
     │                  │                  │                │                │
     │                  │     SAP EWM/MFS Event Mesh       │                │
     │                  │<─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─                │
     │                  │  (Webhook: HMAC-SHA256 verified)  │                │
     │                  │                  │                │                │
     │                  │  Push to CRM ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ >│
     │                  │  (OData API)     │                │                │

4 Data Model & Database Schema

8 PostgreSQL tables with pinaxis_ prefix, Sequelize ORM

Entity Relationship Diagram
  ┌─────────────────────┐
  │  pinaxis_projects    │ ◄─── Central entity: one per prospect analysis
  │─────────────────────│
  │  id (PK)            │
  │  project_code (UQ)  │──┐
  │  company_name       │  │
  │  contact_name/email │  │
  │  industry / country │  │
  │  business_info (J)  │  │  1:N relationships via project_id FK
  │  status             │  │
  │  analysis_started   │  │
  │  analysis_completed │  │
  └─────────────────────┘  │
           │               │
    ┌──────┼───────┬───────┼──────┬──────────┬──────────┬──────────┐
    ▼      ▼       ▼       ▼      ▼          ▼          ▼          ▼
  ┌──────┐┌──────┐┌──────┐┌──────┐┌────────┐┌────────┐┌──────────┐
  │Upload││ Item ││Invent││Goods ││Goods   ││Analysis││Product   │
  │Files ││Master││ory   ││ In   ││ Out    ││Results ││Recommend.│
  │      ││      ││      ││      ││        ││        ││          │
  │file_ ││sku   ││sku   ││rcpt_ ││order_id││analysis││product_  │
  │type  ││dims  ││stock ││id    ││sku     ││_type   ││name      │
  │parse_││weight││loc   ││qty   ││qty     ││result_ ││fit_score │
  │status││bin_  ││snap_ ││date  ││ship_   ││data (J)││reasoning │
  │errors││capab.││date  ││suppl.││date    ││computed││(JSONB)   │
  │(JSON)││(bool)││      ││      ││cust_id ││_at     ││highlight │
  └──────┘└──────┘└──────┘└──────┘└────────┘└────────┘└──────────┘
Table Purpose Key Fields Indexes
pinaxis_projects Project metadata per prospect project_code (unique), company_name, status, business_info (JSONB) [status], [project_code]
pinaxis_uploaded_files File upload tracking file_type, parse_status, parse_errors (JSONB), plausibility_warnings (JSONB) [project_id], [project_id, file_type]
pinaxis_item_master SKU catalog with dimensions sku, length/width/height_mm, weight_kg, bin_capable (computed), batch_tracked [project_id], [project_id, sku]
pinaxis_inventory_data Stock levels by location sku, stock, location, storage_space, snapshot_date [project_id], [project_id, sku]
pinaxis_goods_in_data Inbound deliveries receipt_id, sku, quantity, receipt_date/time, supplier [project_id], [project_id, receipt_date]
pinaxis_goods_out_data Sales orders & shipments order_id, sku, quantity, ship_date/time, customer_id, shipping_method [project_id, ship_date], [project_id, order_id], [project_id, sku]
pinaxis_analysis_results Computed analytics output analysis_type (8 enum values), result_data (JSONB), computed_at [project_id], [project_id, analysis_type] (unique)
pinaxis_product_recommendations GEBHARDT product scores product_name, fit_score (0-100), reasoning (JSONB), highlighted (boolean) [project_id], [project_id, fit_score]

5 Data Ingestion Pipeline

Dual-mode data ingestion: file upload for POC, live API feeds for production

POC Phase — File Upload

For the initial Proof of Concept and sales analysis workflow, data is ingested via CSV/XLSX file uploads. The prospect customer exports data from their WMS/ERP system and uploads 4 files (Item Master, Inventory, Goods-In, Goods-Out) through the PINAXIS dashboard.

  • CSV — auto-detects delimiter (; or ,), UTF-8
  • XLSX — reads first sheet, supports cell dates
  • Max file size: 50 MB (multer memory storage)
Production Phase — Live API Feeds

For live production deployments — after the customer has adopted GEBHARDT automation systems — data ingestion transitions to real-time API-based feeds:

Data SourceProtocolData Scope
SAP EWM OData APIs REST / OData v4 Goods-in movements, goods-out shipments, inventory snapshots, material master data
SAP Event Mesh Webhooks (HMAC-SHA256) Real-time warehouse events — inbound deliveries, pick confirmations, shipping notifications, stock changes
Direct WMS API REST / SOAP For non-SAP customers — connects to any WMS exposing standard warehouse transaction endpoints

In production mode, the analytics engine runs on continuously updated data, enabling live dashboards, trend monitoring, and proactive product recommendations as warehouse patterns evolve.

Column Name Normalization

The parser supports German and English column aliases, allowing PINAXIS customers to use their native column headers:

Input Aliases (DE/EN)Canonical Field
artikel, article, article_number, material, artikelnummer, itemsku
desc, bezeichnung, namedescription
qty, menge, amountquantity
laenge, breite, hoehe, gewichtlength_mm, width_mm, height_mm, weight_kg
uom, einheit, unitunit_of_measure
auftrag, order_noorder_id
lieferschein, delivery_notereceipt_id
lagerort, lagerplatzlocation, storage_space
lieferant, vendorsupplier
versandart, ship_methodshipping_method

Validation Pipeline

  1. Column mapping — normalize headers → canonical names via alias engine
  2. Required field check — verify presence of required columns per file type
  3. Type transforms — parseFloat for dimensions, parseInt for counts, boolean parsing
  4. Plausibility checks — date range span (> 30 days recommended), row count minimum (> 10 rows)
  5. Computed fieldsbin_capable auto-computed from L/W/H vs GEBHARDT standard bins

6 Analytics Engine (8 Computation Types)

SQL-based analytics matching PINAXIS's manual consulting process

1. Overview KPIs

overview_kpis

Total/active/bin-capable SKUs, total orders/orderlines/units, date range, avg lines per order, inventory locations, total stock.

2. Order Structure

order_structure

Orderlines-per-order histogram (1, 2, 3, 4, 5, 6-10, 11-20, 21-50, 50+) with cumulative %, single-line vs multi-line split.

3. Order Time Series

order_time_series

Daily orders/orderlines/units with 7-day moving average. Quartile bands (Q1, median, Q3) for demand variability.

4. Throughput Monthly

throughput_monthly

Orders, orderlines, and units aggregated by YYYY-MM. Reveals seasonality and growth trends.

5. Throughput Weekday

throughput_weekday

Mon-Sun distribution of orders/orderlines/units. Identifies weekday concentration and weekend activity.

6. Throughput Hourly

throughput_hourly

0-23 hour distribution of orderlines using ship_time or picking_time. Identifies peak hours for capacity planning.

7. ABC Classification

abc_classification

Gini coefficient (0-1) measuring demand concentration. Lorenz curve data points. ABC classes: A=80% volume, B=15%, C=5%. Top 20 SKUs.

8. Fit / No-Fit

fit_analysis

SKU dimensions evaluated against 3 GEBHARDT standard bin sizes: 600x400x250mm, 600x400x350mm, 600x400x450mm. Fit % per bin type.

ABC Classification — Gini Coefficient Algorithm

// 1. Query SKU picks sorted ascending (small contributors first) SELECT sku, SUM(quantity) as total_picks FROM pinaxis_goods_out_data WHERE project_id = :projectId GROUP BY sku ORDER BY total_picks ASC // 2. Build Lorenz curve (ascending sort) lorenzCurve = [{x: 0, y: 0}] for (i = 0; i < n; i++) { cumVolume += picks[i] lorenzCurve.push({ x: ((i+1) / n) * 100, y: (cumVolume / totalPicks) * 100 }) } // 3. Compute Gini via trapezoidal integration area = 0 for (i = 1; i < lorenzCurve.length; i++) { dx = (lorenzCurve[i].x - lorenzCurve[i-1].x) / 100 avgY = (lorenzCurve[i].y + lorenzCurve[i-1].y) / 2 / 100 area += dx * avgY } gini = 1 - 2 * area // 0 = perfect equality, 1 = total concentration

7 GEBHARDT Product Matching Engine

Multi-criteria weighted scoring algorithm for 6 product lines

Product Category Key Triggers Top Criteria (weight)
StoreBiter MLS Mini-Load System >70% bin-capable, high SKU count, concentrated ABC bin_capable_pct (0.30), total_skus (0.20), gini (0.15)
StoreBiter OLS Oversize Load >15% oversize items, high weight, medium throughput oversize_pct (0.25), avg_weight_kg (0.20), bin_capable_pct (0.20)
InstaPick Goods-to-Person >30% single-line orders, high pick rate, bin-capable single_line_pct (0.30), orderlines_per_day (0.25), bin_capable_pct (0.20)
ROTA-Sorter Sorting System >20K orders/month, multi-destination, weekday peaks orders_per_month (0.25), multi_line_pct (0.20), weekday_concentration (0.15)
Omnipallet Pallet Handling >20% non-bin-capable, heavy items, pallet volumes non_bin_capable_pct (0.35), avg_weight_kg (0.25), units_per_day (0.15)
Versastore Flexible Automation High SKU diversity, batch tracking, variable demand sku_diversity (0.20), batch_tracked_pct (0.20), daily_variability (0.20)

Scoring Formula

// Per criterion scoring (0-100) if (value >= ideal) score = 100 else if (value <= 0) score = 0 else if (value <= threshold) score = (value / threshold) * 50 else score = 50 + ((value - threshold) / (ideal - threshold)) * 50 // Final product score = weighted average of all criteria fit_score = sum(criterion_score * weight) / sum(weights) // Highlighted (top recommendation) if score >= 70

Extracted Metrics (from analysis results)

MetricSourceComputation
bin_capable_pctfit_analysis / overview_kpis% of SKUs fitting largest GEBHARDT bin
total_skusoverview_kpisCount of item master records
active_sku_ratiooverview_kpisactive SKUs / total SKUs
giniabc_classificationGini coefficient from Lorenz curve
orderlines_per_dayoverview_kpis + date_rangetotal_orderlines / day_count
single_line_pctorder_structure% of orders with exactly 1 line
orders_per_monthoverview_kpis + date_rangetotal_orders / month_count
hourly_peak_ratiothroughput_hourlypeak_hour_orderlines / avg_hour_orderlines
weekday_concentrationthroughput_weekdaymax_weekday_share / total_weekday_volume
daily_variabilityorder_time_seriesstddev(daily_orderlines) / mean(daily_orderlines)

8 SAP EWM/MFS Integration Bridge

How PINAXIS analysis results flow into GEBHARDT's SAP ecosystem

Integration Architecture

SAP EWM/MFS ↔ RinglyPro MCP Bridge
  ┌──────────────────┐          ┌──────────────────┐          ┌──────────────────┐
  │  GEBHARDT PLCs   │◄────────►│  SAP EWM/MFS     │◄────────►│  SAP Event Mesh  │
  │  (StoreBiter,    │ TCP/IP   │  (Warehouse Mgmt │  AMQP/   │  (SAP BTP)       │
  │   InstaPick,     │ Telegram │   Material Flow)  │  MQTT    │                  │
  │   ROTA-Sorter)   │ Protocol │                  │          │                  │
  └──────────────────┘          └────────┬─────────┘          └────────┬─────────┘
                                         │                             │
                                    OData REST API              HTTP POST Webhook
                                    (/SCWM/ ABAP)              (HMAC-SHA256)
                                         │                             │
                                         ▼                             ▼
                                ┌──────────────────────────────────────────────┐
                                │         RinglyPro MCP Server                 │
                                │  ┌────────────────┐  ┌──────────────────┐   │
                                │  │ PINAXIS Module  │  │  Webhook Manager │   │
                                │  │ (Analytics +    │  │  (Event Pipeline │   │
                                │  │  Product Match) │  │   Deduplication) │   │
                                │  └────────────────┘  └──────────────────┘   │
                                │  ┌────────────────┐  ┌──────────────────┐   │
                                │  │  CRM Proxy     │  │  Voice AI (Ana)  │   │
                                │  │  (SAP/GHL/     │  │  (ElevenLabs     │   │
                                │  │   HubSpot)     │  │   multilingual)  │   │
                                │  └────────────────┘  └──────────────────┘   │
                                └──────────────────────────────────────────────┘

SAP Integration Points

InterfaceProtocolDirectionUse Case
OData REST APIs HTTPS + Token Auth Bidirectional Create warehouse orders, read stock levels, push CRM opportunities
SAP Event Mesh AMQP/MQTT → HTTP SAP → MCP Real-time events: order processed, resource malfunction, capacity threshold
SAP Cloud Connector Encrypted tunnel On-prem ↔ BTP Secure bridge for on-premise S/4HANA EWM to cloud services
CDS Views OData SAP → MCP I_WarehouseOrder, I_WarehouseTask — data extraction for analytics
RFC Cloud Connector MCP → SAP Synchronous function module calls for real-time data sync

PLC Communication Protocol (TCP/IP Telegram)

SAP EWM/MFS communicates directly with GEBHARDT PLCs via TCP/IP socket connections using a byte-stream telegram protocol (printable ASCII, up to 4096 bytes):

Telegram Header

Routing & Control

Sender/receiver ID, sequence number, handshake field, telegram type indicator. Every data telegram requires acknowledgement.

Telegram Body

Application Data

HU number, source/destination points, storage bin address, weight, error codes, resource ID. Up to 4096 bytes printable ASCII.

Galileo IoT Bridge

GEBHARDT's Galileo IoT platform provides digital twin telemetry from all installed systems. RinglyPro captures these signals via webhooks for:

9 API Reference

All endpoints under /pinaxis/api/v1/

MethodEndpointDescription
GET/pinaxis/healthHealth check with DB status
Projects
POST/api/v1/projectsCreate new analysis project
GET/api/v1/projectsList all projects
GET/api/v1/projects/:idGet project with files, results, recommendations
PATCH/api/v1/projects/:idUpdate project metadata
Upload
POST/api/v1/upload/:projectId/:fileTypeUpload CSV/XLSX (item_master, inventory, goods_in, goods_out)
GET/api/v1/upload/:projectId/statusUpload status for all file types
Analysis
POST/api/v1/analysis/:projectId/runExecute all 8 analytics
GET/api/v1/analysis/:projectId/allGet all results at once
GET/api/v1/analysis/:projectId/overviewOverview KPIs
GET/api/v1/analysis/:projectId/order-structureOrder composition histogram
GET/api/v1/analysis/:projectId/order-time-seriesDaily order trends + moving avg
GET/api/v1/analysis/:projectId/throughputMonthly + weekday + hourly
GET/api/v1/analysis/:projectId/abcABC + Gini + Lorenz curve
GET/api/v1/analysis/:projectId/fit-analysisBin fit analysis (3 sizes)
Products
POST/api/v1/products/:projectId/matchRun product matching algorithm
GET/api/v1/products/:projectId/recommendationsGet scored product recommendations
Reports
POST/api/v1/reports/:projectId/generateGenerate PDF report
GET/api/v1/reports/:projectId/downloadDownload PDF (application/pdf)
Demo
POST/api/v1/demo/generateCreate demo project with synthetic data

10 Dashboard Architecture

React 18 + Vite + TailwindCSS + Recharts

Technology Stack

LayerTechnologyVersion
FrameworkReact18.3.1
BuildVite6.0.0
StylingTailwindCSS3.4.17
ChartsRecharts2.15.0
RoutingReact Router6.28.0
Uploadreact-dropzone14.3.5
Base Path/pinaxis/

Component Architecture

Pages

4 Route Pages

UploadPage (/) — 3-step wizard: company info → file uploads → run analysis.
AnalysisPage (/analysis/:id) — all 8 chart components.
ProductsPage (/products/:id) — recommendation cards.
ReportPage (/report/:id) — preview + PDF download.

Charts

7 Visualization Components

KpiCards (8 metrics), OrderStructureChart (histogram + cumulative line), ThroughputChart (monthly bars with metric toggle), WeekdayChart (grouped bars Mon-Sun), HourlyChart (24h bars), ABCLorenzCurve (Gini + curve), FitAnalysisTable (bin sizes + progress bars).

UI Components

3 Interaction Components

FileUploader (react-dropzone, status badges, error display), StepIndicator (4-step horizontal progress), ProductCard (score circle, category badge, expandable reasoning accordion).

Build Output

11 PDF Report Generator

Server-side PDF generation with pdfmake (~40KB per report)

Report Sections

  1. Cover Page — PINAXIS branding, company name, project code, generation date, "Powered by GEBHARDT"
  2. Overview KPIs — 4-column metric table (SKUs, orders, units, date range)
  3. Order Structure — Histogram table with line count bins and cumulative %
  4. Throughput Analysis — Monthly and weekday tables with orders/orderlines/units
  5. ABC Classification — A/B/C class summary table + Gini coefficient + top 10 SKU table
  6. Fit Analysis — 3 bin sizes with fit count/% and dimension comparison
  7. Product Recommendations — 6 GEBHARDT products with score circles (color-coded), category, description

Technical Implementation

12 Security & Authentication

POC scope with path to production-grade security

Access Control

Project-Code Authentication

POC uses simple project-code access (e.g., PINAXIS-2026-001). URL pattern: /pinaxis/?project=CODE. Path to production: JWT token per project.

Webhook Security

HMAC-SHA256 Verification

All incoming webhooks from SAP Event Mesh verified via HMAC-SHA256 signature. Event deduplication prevents replay attacks.

Transport

HTTPS + SSL

All API endpoints served over HTTPS via Render. PostgreSQL connections use SSL with require: true. SAP Cloud Connector provides encrypted tunnel.

Data Isolation

Project-Level Scoping

Every query scoped by project_id foreign key. No cross-project data leakage. File uploads stored in memory (not disk), processed and discarded.

13 Deployment & Infrastructure

Production deployment on Render with auto-deploy CI/CD

ComponentSpecification
PlatformRender (auto-deploy on push to main)
RuntimeNode.js 18+ on Render
DatabasePostgreSQL on Render (shared with RinglyPro CRM)
Deploy Time~2 minutes after git push
Build Scriptbuild.sh — installs deps, seeds DB, builds 4 dashboards
Dashboard URLhttps://aiagent.ringlypro.com/pinaxis/
Health Checkhttps://aiagent.ringlypro.com/pinaxis/health
API Basehttps://aiagent.ringlypro.com/pinaxis/api/v1/
Debug Endpointhttps://aiagent.ringlypro.com/debug/pinaxis-error

Backend Dependencies

PackagePurpose
expressHTTP server framework
sequelize + pgORM + PostgreSQL driver
xlsxExcel file parsing
csv-parseCSV file parsing
pdfmakePDF report generation
multerFile upload middleware (memory storage)
helmet + corsSecurity headers + CORS

14 Implementation Roadmap

4-week POC sprint + 12-week full integration

POC Sprint (Weeks 1-4) — Completed

WeekDeliverablesStatus
Week 1 Module scaffold, 8 Sequelize models, Express sub-app, mount in app.js, deploy Done
Week 2 CSV/XLSX parser, 8 analytics (overview, orders, throughput, ABC, fit), synthetic data generator Done
Week 3 GEBHARDT product matching engine, React dashboard (10 components), PDF report generator Done
Week 4 Build integration, deploy, demo with synthetic data, end-to-end verification Done

Full Integration (Weeks 5-16) — Planned

PhaseDeliverables
Phase 2 (Wk 5-8) SAP Event Mesh webhook integration, Galileo IoT bridge, predictive maintenance dispatch, Voice AI (Ana) knowledge update for PINAXIS
Phase 3 (Wk 9-12) Business Collector for warehouse expansion leads, AI Copilot trained on GEBHARDT products, ROI calculator + auto-proposal generation
Phase 4 (Wk 13-16) Full CRM sync (SAP/GHL), enterprise account orchestration, trade show pipeline, performance analytics dashboard, production hardening