# pmcgee-personal/shipstation-partnerapi-sales-demo architecture

> Architecture diagram of the GitHub repository pmcgee-personal/shipstation-partnerapi-sales-demo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pmcgee-personal/shipstation-partnerapi-sales-demo
- Repository: https://github.com/pmcgee-personal/shipstation-partnerapi-sales-demo

## Overview

This is a sales demo harness for provisioning ShipStation accounts and managing carriers, warehouses, and ShipEngine Elements settings. The user path runs from Cognito email-OTP sign-in through the demo account control bar and Modern WMS pages to authenticated API Gateway/Lambda operations, with account records in DynamoDB and ShipEngine integrations. The graph reflects documented capabilities; unsampled handler routes and AWS wiring are summarized where exact call relationships are not visible in excerpts.

Main entry points: [`backend/handler.js`](https://github.com/pmcgee-personal/shipstation-partnerapi-sales-demo/blob/main/backend/handler.js) (API handlers), [`frontend/src/services/api.js`](https://github.com/pmcgee-personal/shipstation-partnerapi-sales-demo/blob/main/frontend/src/services/api.js) (API client), [`frontend/src/shells/modern-wms/CarrierSettings.jsx`](https://github.com/pmcgee-personal/shipstation-partnerapi-sales-demo/blob/main/frontend/src/shells/modern-wms/CarrierSettings.jsx) (Carrier settings), [`frontend/src/App.jsx`](https://github.com/pmcgee-personal/shipstation-partnerapi-sales-demo/blob/main/frontend/src/App.jsx) (App shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Demo interface"]
  node_app["App shell<br/>[App.jsx]"]
  node_login["OTP login gate<br/>[LoginGate.jsx]"]
  node_session[("Local session<br/>[auth.js]")]
  node_demo_bar["Demo account controls<br/>[DemoBar.jsx]"]
  node_api_client["API client<br/>[api.js]"]
  node_layout["Modern WMS layout<br/>[Layout.jsx]"]
  node_dashboard["Demo dashboard<br/>[DashboardPage.jsx]"]
  node_carrier_settings["Carrier settings"]
  node_carrier_table["Carrier table<br/>[CarrierTable.jsx]"]
  node_warehouse_section["Warehouse locations"]
  node_location_table["Location table<br/>[LocationTable.jsx]"]
  node_elements_page["Elements settings"]
end

subgraph group_backend["API and identity"]
  node_lambda["API handlers<br/>[handler.js]"]
  node_validation["Request validation<br/>[validation.js]"]
  node_otp_auth["Cognito OTP helpers<br/>[auth.js]"]
  node_api_gateway["API Gateway"]
end

subgraph group_data["Account data"]
  node_accounts_db[("Account records<br/>[database.js]")]
end

subgraph group_integrations["Partner services"]
  node_shipengine_client["Partner API client<br/>[api-clients.js]"]
  node_warehouse_helpers["Warehouse helpers<br/>[warehouse.js]"]
  node_cognito["Amazon Cognito"]
  node_shipengine["ShipEngine APIs"]
  node_elements["ShipEngine Elements"]
  node_ssm[("AWS SSM secrets")]
end

node_sales_rep(("Sales rep"))

node_sales_rep -->|"uses"| node_app
node_app -->|"gates access"| node_login
node_app -->|"renders"| node_demo_bar
node_app -->|"renders"| node_layout
node_login -->|"requests OTP"| node_api_client
node_login -->|"stores session"| node_session
node_api_client -->|"gets token"| node_session
node_api_client -->|"sends requests"| node_api_gateway
node_demo_bar -->|"manages accounts"| node_api_client
node_layout -->|"renders"| node_dashboard
node_layout -->|"renders"| node_carrier_settings
node_layout -->|"renders"| node_elements_page
node_carrier_settings -->|"loads carriers"| node_api_client
node_carrier_settings -->|"loads warehouses"| node_api_client
node_carrier_settings -->|"renders"| node_carrier_table
node_carrier_settings -->|"renders"| node_warehouse_section
node_warehouse_section -->|"renders"| node_location_table
node_elements_page -->|"gets JWT"| node_api_client
node_elements_page -->|"mounts settings"| node_elements
node_api_gateway -->|"routes requests"| node_lambda
node_lambda -->|"validates input"| node_validation
node_lambda -->|"handles OTP"| node_otp_auth
node_otp_auth -->|"provisions and verifies"| node_cognito
node_lambda -.->|"reads and writes"| node_accounts_db
node_lambda -->|"calls partner endpoints"| node_shipengine
node_lambda -->|"reads signing secrets"| node_ssm
node_lambda -->|"signs Elements token"| node_shipengine
node_shipengine_client -.->|"supports integration"| node_shipengine
node_warehouse_helpers -.->|"supports warehouse flow"| node_shipengine

click node_app "https://github.com/pmcgee-personal/shipstation-partnerapi-sales-demo/blob/main/frontend/src/App.jsx"
click node_login "https://github.com/pmcgee-personal/shipstation-partnerapi-sales-demo/blob/main/frontend/src/components/LoginGate.jsx"
click node_session "https://github.com/pmcgee-personal/shipstation-partnerapi-sales-demo/blob/main/frontend/src/services/auth.js"
click node_demo_bar "https://github.com/pmcgee-personal/shipstation-partnerapi-sales-demo/blob/main/frontend/src/components/DemoBar.jsx"
click node_api_client "https://github.com/pmcgee-personal/shipstation-partnerapi-sales-demo/blob/main/frontend/src/services/api.js"
click node_layout "https://github.com/pmcgee-personal/shipstation-partnerapi-sales-demo/blob/main/frontend/src/shells/modern-wms/Layout.jsx"
click node_dashboard "https://github.com/pmcgee-personal/shipstation-partnerapi-sales-demo/blob/main/frontend/src/shells/modern-wms/DashboardPage.jsx"
click node_carrier_settings "https://github.com/pmcgee-personal/shipstation-partnerapi-sales-demo/blob/main/frontend/src/shells/modern-wms/CarrierSettings.jsx"
click node_carrier_table "https://github.com/pmcgee-personal/shipstation-partnerapi-sales-demo/blob/main/frontend/src/components/CarrierTable.jsx"
click node_warehouse_section "https://github.com/pmcgee-personal/shipstation-partnerapi-sales-demo/blob/main/frontend/src/shells/modern-wms/WarehouseLocationsSection.jsx"
click node_location_table "https://github.com/pmcgee-personal/shipstation-partnerapi-sales-demo/blob/main/frontend/src/components/LocationTable.jsx"
click node_elements_page "https://github.com/pmcgee-personal/shipstation-partnerapi-sales-demo/blob/main/frontend/src/shells/modern-wms/AccountSettingsElement.jsx"
click node_lambda "https://github.com/pmcgee-personal/shipstation-partnerapi-sales-demo/blob/main/backend/handler.js"
click node_validation "https://github.com/pmcgee-personal/shipstation-partnerapi-sales-demo/blob/main/backend/utils/validation.js"
click node_otp_auth "https://github.com/pmcgee-personal/shipstation-partnerapi-sales-demo/blob/main/backend/utils/auth.js"
click node_accounts_db "https://github.com/pmcgee-personal/shipstation-partnerapi-sales-demo/blob/main/backend/utils/database.js"
click node_shipengine_client "https://github.com/pmcgee-personal/shipstation-partnerapi-sales-demo/blob/main/backend/utils/api-clients.js"
click node_warehouse_helpers "https://github.com/pmcgee-personal/shipstation-partnerapi-sales-demo/blob/main/backend/utils/warehouse.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_login,node_session,node_demo_bar,node_api_client,node_layout,node_dashboard,node_carrier_settings,node_carrier_table,node_warehouse_section,node_location_table,node_elements_page toneBlue
class node_lambda,node_validation,node_otp_auth,node_api_gateway toneAmber
class node_accounts_db toneMint
class node_shipengine_client,node_warehouse_helpers,node_cognito,node_shipengine,node_elements,node_ssm toneRose
class node_sales_rep toneIndigo
```

## Components

### Demo interface

- [App shell](https://github.com/pmcgee-personal/shipstation-partnerapi-sales-demo/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [OTP login gate](https://github.com/pmcgee-personal/shipstation-partnerapi-sales-demo/blob/main/frontend/src/components/LoginGate.jsx): `frontend/src/components/LoginGate.jsx`
- [Local session](https://github.com/pmcgee-personal/shipstation-partnerapi-sales-demo/blob/main/frontend/src/services/auth.js): `frontend/src/services/auth.js`
- [Demo account controls](https://github.com/pmcgee-personal/shipstation-partnerapi-sales-demo/blob/main/frontend/src/components/DemoBar.jsx): `frontend/src/components/DemoBar.jsx`
- [API client](https://github.com/pmcgee-personal/shipstation-partnerapi-sales-demo/blob/main/frontend/src/services/api.js): `frontend/src/services/api.js`
- [Modern WMS layout](https://github.com/pmcgee-personal/shipstation-partnerapi-sales-demo/blob/main/frontend/src/shells/modern-wms/Layout.jsx): `frontend/src/shells/modern-wms/Layout.jsx`
- [Demo dashboard](https://github.com/pmcgee-personal/shipstation-partnerapi-sales-demo/blob/main/frontend/src/shells/modern-wms/DashboardPage.jsx): `frontend/src/shells/modern-wms/DashboardPage.jsx`
- [Carrier settings](https://github.com/pmcgee-personal/shipstation-partnerapi-sales-demo/blob/main/frontend/src/shells/modern-wms/CarrierSettings.jsx): `frontend/src/shells/modern-wms/CarrierSettings.jsx`
- [Carrier table](https://github.com/pmcgee-personal/shipstation-partnerapi-sales-demo/blob/main/frontend/src/components/CarrierTable.jsx): `frontend/src/components/CarrierTable.jsx`
- [Warehouse locations](https://github.com/pmcgee-personal/shipstation-partnerapi-sales-demo/blob/main/frontend/src/shells/modern-wms/WarehouseLocationsSection.jsx): `frontend/src/shells/modern-wms/WarehouseLocationsSection.jsx`
- [Location table](https://github.com/pmcgee-personal/shipstation-partnerapi-sales-demo/blob/main/frontend/src/components/LocationTable.jsx): `frontend/src/components/LocationTable.jsx`
- [Elements settings](https://github.com/pmcgee-personal/shipstation-partnerapi-sales-demo/blob/main/frontend/src/shells/modern-wms/AccountSettingsElement.jsx): `frontend/src/shells/modern-wms/AccountSettingsElement.jsx`

### API and identity

- [API handlers](https://github.com/pmcgee-personal/shipstation-partnerapi-sales-demo/blob/main/backend/handler.js): `backend/handler.js`
- [Request validation](https://github.com/pmcgee-personal/shipstation-partnerapi-sales-demo/blob/main/backend/utils/validation.js): `backend/utils/validation.js`
- [Cognito OTP helpers](https://github.com/pmcgee-personal/shipstation-partnerapi-sales-demo/blob/main/backend/utils/auth.js): `backend/utils/auth.js`
- **API Gateway**

### Account data

- [Account records](https://github.com/pmcgee-personal/shipstation-partnerapi-sales-demo/blob/main/backend/utils/database.js): `backend/utils/database.js`

### Partner services

- [Partner API client](https://github.com/pmcgee-personal/shipstation-partnerapi-sales-demo/blob/main/backend/utils/api-clients.js): `backend/utils/api-clients.js`
- [Warehouse helpers](https://github.com/pmcgee-personal/shipstation-partnerapi-sales-demo/blob/main/backend/utils/warehouse.js): `backend/utils/warehouse.js`
- **Amazon Cognito**
- **ShipEngine APIs**
- **ShipEngine Elements**
- **AWS SSM secrets**

### Other components

- **Sales rep**

## Connections

- Sales rep → App shell: uses (evidence: `frontend/src/App.jsx`)
- App shell → OTP login gate: gates access (evidence: `frontend/src/App.jsx`)
- App shell → Demo account controls: renders (evidence: `frontend/src/App.jsx`)
- App shell → Modern WMS layout: renders (evidence: `frontend/src/App.jsx`)
- OTP login gate → API client: requests OTP (evidence: `frontend/src/components/LoginGate.jsx`)
- OTP login gate → Local session: stores session (evidence: `frontend/src/components/LoginGate.jsx`)
- API client → Local session: gets token (evidence: `frontend/src/services/api.js`)
- API client → API Gateway: sends requests (evidence: `frontend/src/services/api.js`)
- Demo account controls → API client: manages accounts (evidence: `frontend/src/components/DemoBar.jsx`)
- Modern WMS layout → Demo dashboard: renders (evidence: `frontend/src/shells/modern-wms/Layout.jsx`)
- Modern WMS layout → Carrier settings: renders (evidence: `frontend/src/shells/modern-wms/Layout.jsx`)
- Modern WMS layout → Elements settings: renders (evidence: `frontend/src/shells/modern-wms/Layout.jsx`)
- Carrier settings → API client: loads carriers (evidence: `frontend/src/shells/modern-wms/CarrierSettings.jsx`)
- Carrier settings → API client: loads warehouses (evidence: `frontend/src/shells/modern-wms/CarrierSettings.jsx`)
- Carrier settings → Carrier table: renders
- Carrier settings → Warehouse locations: renders (evidence: `frontend/src/shells/modern-wms/CarrierSettings.jsx`)
- Warehouse locations → Location table: renders (evidence: `frontend/src/shells/modern-wms/WarehouseLocationsSection.jsx`)
- Elements settings → API client: gets JWT (evidence: `frontend/src/shells/modern-wms/AccountSettingsElement.jsx`)
- Elements settings → ShipEngine Elements: mounts settings (evidence: `readme.md`)
- API Gateway → API handlers: routes requests (evidence: `readme.md`)
- API handlers → Request validation: validates input (evidence: `backend/handler.js`)
- API handlers → Cognito OTP helpers: handles OTP (evidence: `backend/handler.js`)
- Cognito OTP helpers → Amazon Cognito: provisions and verifies (evidence: `backend/utils/auth.js`)
- API handlers → Account records: reads and writes
- API handlers → ShipEngine APIs: calls partner endpoints (evidence: `readme.md`)
- API handlers → AWS SSM secrets: reads signing secrets (evidence: `backend/handler.js`)
- API handlers → ShipEngine APIs: signs Elements token (evidence: `readme.md`)
- Partner API client → ShipEngine APIs: supports integration
- Warehouse helpers → ShipEngine APIs: supports warehouse flow