Documentation

Complete guide for installing, configuring, and deploying GoodsMart WMS.

System Architecture

GoodsMart WMS Ecosystem
├── 🖥️ GoodsMart-WMS-Backend    — Flask API Service
├── 🌐 GoodsMart-WMS-Web        — Nuxt.js 4 Web Client
├── 📱 GoodsMart-WMS-Mobile     — Mobile App (Coming Soon)
└── 📚 GoodsMart-WMS-Website    — Product Website

Prerequisites

Ensure the following software is installed before starting:

Quick Start

Get the full system running in minutes with these steps.

git clone https://github.com/loadstarCN/GoodsMart-WMS-Backend.git
cd GoodsMart-WMS-Backend
python -m venv venv
source venv/bin/activate      # Windows: venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env          # Edit .env with your config
flask db init
flask db migrate -m "Initial"
flask db upgrade
python app.py

git clone https://github.com/loadstarCN/GoodsMart-WMS-Web.git
cd GoodsMart-WMS-Web
npm install
cp .env.example .env          # Set API_BASE_URL=http://localhost:5000
npm run dev

Backend Setup

Tech Stack

Project Structure

GoodsMart-WMS-Backend/
├── app.py                    # Application entry
├── config.py                 # Configuration
├── .env                      # Environment variables
├── requirements.txt          # Dependencies
├── migrations/               # DB migrations (Alembic)
├── extensions/               # Flask extensions
│   ├── db.py, jwt.py, mqtt.py, celery.py
├── system/                   # Core modules
│   ├── auth/                 # Auth & permissions
│   ├── inventory/            # Inventory management
│   ├── order/                # Order management
│   ├── warehouse/            # Warehouse management
│   └── ...
├── tasks/                    # Celery async tasks
├── utils/                    # Helpers & validators
└── tests/                    # Test suite

Environment Configuration

Copy .env.example to .env and configure the following variables:

# Application
FLASK_ENV=development
FLASK_DEBUG=True

# Database
SQLALCHEMY_DATABASE_URI=postgresql://user:pass@localhost:5432/warehouse_db

# JWT
JWT_SECRET_KEY=your_secure_random_jwt_secret_key

# Redis
REDIS_URL=redis://localhost:6379/0

# MQTT (Optional - for IoT)
MQTT_BROKER_URL=your.mqtt.broker.url
MQTT_BROKER_PORT=1883

# Client
CLIENT_BASE_URL=http://localhost:3000

Database Management

flask db init
flask db migrate -m "Initial migration"
flask db upgrade

flask db migrate -m "Add new feature"
flask db upgrade

flask db downgrade

API Modules

The backend exposes a RESTful API organized into the following modules. Interactive API docs are available at /system/doc (Swagger UI).

Error Codes

The API uses a structured error code system for consistent error handling.

Frontend Setup

Tech Stack

Installation

git clone https://github.com/loadstarCN/GoodsMart-WMS-Web.git
cd GoodsMart-WMS-Web
npm install
cp .env.example .env

Configure your .env:

API_BASE_URL=http://localhost:5000
NUXT_PUBLIC_ENCRYPTION_KEY=# openssl rand -base64 32

Frontend Project Structure

GoodsMart-WMS-Web/
├── assets/          # Styles, images
├── components/      # Vue components
├── composables/     # Composable functions
├── layouts/         # Layout components
├── locales/         # i18n translation files
├── middleware/      # Route middleware
├── pages/           # Page components (auto-routing)
├── plugins/         # Nuxt plugins
├── public/          # Static assets
├── server/          # Server middleware
├── stores/          # Pinia stores
├── types/           # TypeScript types
└── utils/           # Utility functions

Deployment

To deploy the full GoodsMart WMS system, you need: the API service, the web client, PostgreSQL, and Redis.

Backend (Gunicorn)

pip install gunicorn
gunicorn -w 4 -b 0.0.0.0:5000 app:app

Frontend (PM2)

npm run build
npm install -g pm2
pm2 start ecosystem.config.js

Supervisord Config

# /etc/supervisor/conf.d/wms-api.conf
[program:wms-api]
directory=/path/to/GoodsMart-WMS-Backend
command=gunicorn -w 4 -b 0.0.0.0:5000 app:app
autostart=true
autorestart=true
environment=FLASK_ENV="production"
user=www-data

MQTT Integration

GoodsMart WMS supports MQTT for IoT device integration such as barcode scanners and sensors.

Subscribe to Messages

from extensions import mqtt_client

def handle_sensor_data(topic, payload):
    print(f"Received from {topic}: {payload}")

mqtt_client.subscribe('sensors/#', handle_sensor_data)

Publish Messages

from extensions import mqtt_client

mqtt_client.publish(
    'devices/light/control',
    {'action': 'on', 'duration': 30}
)

Contributing

We welcome contributions of all kinds! Here's how to get started:

1. Fork the repository on GitHub
2. Create a feature branch: git checkout -b feature/AmazingFeature
3. Commit your changes: git commit -m 'Add AmazingFeature'
4. Push to your branch: git push origin feature/AmazingFeature
5. Open a Pull Request

License

GoodsMart WMS is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).

For commercial licensing inquiries, contact goodsmart@goodsmart.jp.