Project Structure

A well-organized project structure makes shop integrations easier to build and maintain. This page describes the recommended layout based on the VARIO App Demo, extended for shop and marketplace use cases.

Starting Point

Clone the demo app as your starting point:

git clone https://github.com/vario-software/vario-app-demo.git my-shop-app
cd my-shop-app
npm install

Recommended Layout

my-shop-app/
├── backend/
│   ├── index.js                          # App entry point
│   ├── routes/
│   │   ├── maintenance.js                # Install/uninstall endpoints
│   │   ├── webhooks.js                   # Webhook receivers
│   │   ├── orders.js                     # Order-related endpoints
│   │   ├── products.js                   # Product-related endpoints
│   │   └── mappings.js                   # Mapping configuration endpoints
│   └── services/
│       ├── inbound/                      # Platform → ERP
│       │   ├── orders/
│       │   │   ├── fetch.js              # Fetch orders from platform
│       │   │   └── transform.js          # Transform to ERP format
│       │   ├── products/
│       │   │   ├── fetch.js
│       │   │   └── transform.js
│       │   └── customers/
│       │       ├── fetch.js
│       │       └── transform.js
│       ├── outbound/                     # ERP → Platform
│       │   ├── articles/
│       │   │   ├── fetch.js              # Fetch from ERP via VQL
│       │   │   ├── transform.js          # Transform to platform format
│       │   │   └── sync.js               # Push to platform API
│       │   ├── stock/
│       │   │   ├── fetch.js
│       │   │   └── sync.js
│       │   ├── prices/
│       │   │   ├── fetch.js
│       │   │   └── sync.js
│       │   └── order-status/
│       │       ├── fetch.js
│       │       └── sync.js
│       └── maintenance/
│           ├── install.js                # Installation orchestrator
│           ├── uninstall.js              # Cleanup logic
│           └── migrations/
│               └── 1/
│                   └── index.js          # Initial migration
├── frontend/
│   ├── index.html                        # Main UI page
│   ├── install.html                      # Installation UI
│   ├── script/
│   │   └── main.js                       # Frontend logic
│   └── package.json                      # Frontend dependencies
├── app-manifest.json                     # App metadata and permissions
├── app-client.json                       # OAuth credentials (git-ignored)
├── package.json
└── .gitignore

Key Directories

backend/routes/

Each route file handles a specific concern:

• maintenance.js — Install, uninstall, and manifest endpoints. These are called by VARIO Cloud during the app lifecycle.

• webhooks.js — Receives webhook notifications from the ERP (article updates, stock changes, etc.). Should respond immediately and process asynchronously.

• orders.js — Endpoints for order import triggers and order-related operations.

• products.js — Endpoints for product listing management.

• mappings.js — CRUD endpoints for managing entity mappings (payment methods, shipping, categories, etc.).

backend/services/inbound/

Contains services that handle data flowing from the external platform into VARIO ERP. Each entity type (orders, products, customers) gets its own directory with:

• fetch.js — Retrieves data from the platform API

• transform.js — Maps platform data structures to the VARIO ERP format

backend/services/outbound/

Contains services that handle data flowing from VARIO ERP to the external platform. Each entity type gets:

• fetch.js — Queries VARIO ERP data using VQL or the REST API

• transform.js — Maps ERP data to the platform's expected format

• sync.js — Pushes transformed data to the platform API

backend/services/maintenance/

Handles the app lifecycle:

• install.js — Orchestrates the installation process (offline token storage, migrations)

• uninstall.js — Cleans up app resources when the app is removed

• migrations/ — Numbered migration directories that run sequentially during installation

frontend/

Static frontend assets served by the framework. No build step required — uses native ES modules and the framework's CSS.

Configuration Files

app-manifest.json

Defines your app's metadata, permissions, and UI integration points. For shop apps, you will need permissions for sales channels, articles, stock, prices, documents, EAV, and data imports. See the App Manifest for Shop Apps reference.

app-client.json

Stores your OAuth credentials. This file must be git-ignored:

{
  "appIdentifier": "",
  "clientId": "",
  "clientSecret": "",
  "appJWK": ""
}

Never commit app-client.json to version control. Add it to your .gitignore file.

package.json

Your root package.json should include the framework backend dependency:

{
  "dependencies": {
    "@vario-software/vario-app-framework-backend": "^2026.6.0"
  }
}

The frontend package.json (in frontend/) includes the frontend framework:

{
  "dependencies": {
    "@vario-software/vario-app-framework-frontend": "^2026.6.0"
  }
}