https://github.com/xshopai/inventory-service

Tracks stock levels, availability, and inventory updates.
https://github.com/xshopai/inventory-service

flask microservice mysql python xshopai

Last synced: 3 months ago
JSON representation

Tracks stock levels, availability, and inventory updates.

Host: GitHub
URL: https://github.com/xshopai/inventory-service
Owner: xshopai
License: mit
Created: 2025-08-27T21:51:05.000Z (10 months ago)
Default Branch: main
Last Pushed: 2026-02-27T14:52:32.000Z (4 months ago)
Last Synced: 2026-02-27T18:44:59.892Z (4 months ago)
Topics: flask, microservice, mysql, python, xshopai
Language: Python
Homepage:
Size: 567 KB
Stars: 1
Watchers: 0
Forks: 0
Open Issues: 8
Metadata Files:
- Readme: README.md
- License: LICENSE
- Security: .github/SECURITY.md

Awesome Lists containing this project

README

# 📦 Inventory Service

**Enterprise-grade inventory management microservice for the xshopai e-commerce platform**

[![Python](https://img.shields.io/badge/Python-3.11+-3776AB?style=for-the-badge&logo=python&logoColor=white)](https://python.org)
[![Flask](https://img.shields.io/badge/Flask-3.0+-000000?style=for-the-badge&logo=flask&logoColor=white)](https://flask.palletsprojects.com)
[![MySQL](https://img.shields.io/badge/MySQL-8.0+-4479A1?style=for-the-badge&logo=mysql&logoColor=white)](https://mysql.com)
[![Dapr](https://img.shields.io/badge/Dapr-Enabled-0D597F?style=for-the-badge&logo=dapr&logoColor=white)](https://dapr.io)
[![License](https://img.shields.io/badge/License-Proprietary-red?style=for-the-badge)](LICENSE)

[Getting Started](#-getting-started) •
[Documentation](#-documentation) •
[API Reference](docs/PRD.md) •
[Contributing](#-contributing)

---

## 🎯 Overview

The **Inventory Service** is a critical microservice responsible for managing real-time stock levels, reservations, stock movements, and event-driven inventory synchronization across the xshopai platform. Built with scalability and reliability in mind, it supports multi-cloud deployments and integrates seamlessly with the broader microservices ecosystem.

---

## ✨ Key Features

### 📊 Stock Management

- Real-time inventory tracking
- Multi-variant product support
- Low stock alerts & thresholds
- Automatic stock reconciliation

### 🔒 Reservation System

- Time-limited stock reservations
- Automatic expiration handling
- Order processing integration
- Concurrent access control

### 📡 Event-Driven Architecture

- CloudEvents 1.0 specification
- Pub/sub messaging integration
- Real-time inventory updates
- Cross-service synchronization

### 🛡️ Enterprise Security

- JWT token authentication
- Service-to-service tokens
- Role-based access control
- Complete audit trail

---

## 🚀 Getting Started

### Prerequisites

- Python 3.11+
- MySQL 8.0+
- Docker & Docker Compose (optional)
- Dapr CLI (for production-like setup)

### Quick Start with Docker Compose

```bash
# Clone the repository
git clone https://github.com/xshopai/inventory-service.git
cd inventory-service

# Start all services (MySQL, service, etc.)
docker-compose up -d

# Verify the service is healthy
curl http://localhost:8005/health
```

### Local Development Setup

🔧 Without Dapr (Simple Setup)

```bash
# Create virtual environment
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Set up environment variables
cp .env.example .env
# Edit .env with your configuration

# Run database migrations
flask db upgrade

# Start the service
python run.py
```

📖 See [Local Development Guide](docs/LOCAL_DEVELOPMENT.md) for detailed instructions.

⚡ With Dapr (Production-like)

```bash
# Ensure Dapr is initialized
dapr init

# Start with Dapr sidecar
dapr run \
--app-id inventory-service \
--app-port 8005 \
--dapr-http-port 3500 \
--resources-path .dapr/components \
--config .dapr/config.yaml \
-- python run.py
```

> **Note:** All services now use the standard Dapr ports (3500 for HTTP, 50001 for gRPC). This simplifies configuration and works consistently whether running via Docker Compose or individual service runs.

📖 See [Dapr Development Guide](docs/LOCAL_DEVELOPMENT_DAPR.md) for detailed instructions.

---

## 📚 Documentation

| Document | Description |
| :--------------------------------------------------------------- | :--------------------------------------------------- |
| 📘 [Local Development](docs/LOCAL_DEVELOPMENT.md) | Step-by-step local setup without Dapr |
| ⚡ [Local Development with Dapr](docs/LOCAL_DEVELOPMENT_DAPR.md) | Local setup with full Dapr integration |
| ☁️ [Azure Container Apps](docs/ACA_DEPLOYMENT.md) | Deploy to serverless containers with built-in Dapr |
| 📋 [Product Requirements](docs/PRD.md) | Complete API specification and business requirements |
| 🏗️ [Architecture](docs/ARCHITECTURE.md) | System design, patterns, and data flows |
| 🔐 [Security](.github/SECURITY.md) | Security policies and vulnerability reporting |

---

## 🧪 Testing

We maintain high code quality standards with comprehensive test coverage.

```bash
# Run all unit tests
pytest tests/unit/ -v

# Run with coverage report
pytest --cov=src --cov-report=html --cov-report=term-missing

# Run specific test file
pytest tests/unit/test_inventory_service.py -v

# Run integration tests (requires running services)
pytest tests/integration/ -v
```

### Test Coverage

---

## 🏗️ Project Structure

```
inventory-service/
├── 📁 src/ # Application source code
│ ├── 📁 controllers/ # REST API endpoints
│ ├── 📁 services/ # Business logic layer
│ ├── 📁 repositories/ # Data access layer
│ ├── 📁 models/ # SQLAlchemy models
│ ├── 📁 messaging/ # Messaging abstraction (Dapr/ServiceBus/RabbitMQ)
│ ├── 📁 middlewares/ # Authentication, logging, tracing
│ └── 📁 utils/ # Helper functions & utilities
├── 📁 tests/ # Test suite
│ ├── 📁 unit/ # Unit tests
│ ├── 📁 integration/ # Integration tests
│ └── 📁 e2e/ # End-to-end tests
├── 📁 migrations/ # Alembic database migrations
├── 📁 .dapr/ # Dapr configuration
│ ├── 📁 components/ # Pub/sub, secrets, state stores
│ └── 📄 config.yaml # Dapr runtime configuration
├── 📁 docs/ # Documentation
├── 📄 docker-compose.yml # Local containerized environment
├── 📄 Dockerfile # Production container image
└── 📄 requirements.txt # Python dependencies
```

---

## 🔧 Technology Stack

---

## ⚡ Quick Reference

```bash
# 🐳 Docker Compose
docker-compose up -d # Start all services
docker-compose down # Stop all services
docker-compose logs -f inventory # View logs

# 🐍 Local Development
python run.py # Run without Dapr
flask db upgrade # Apply migrations
flask db migrate -m "message" # Create migration

# ⚡ Dapr Development
dapr run --app-id inventory-service --app-port 8005 -- python run.py

# 🧪 Testing
pytest tests/unit/ -v # Run unit tests
pytest --cov=src # Run with coverage

# 🔍 Health Check
curl http://localhost:8005/health
curl http://localhost:8005/health/ready
```

---

## 🤝 Contributing

We welcome contributions! Please follow these steps:

1. **Fork** the repository
2. **Create** a feature branch
```bash
git checkout -b feature/amazing-feature
```
3. **Write** tests for your changes
4. **Run** the test suite
```bash
pytest && black . && flake8
```
5. **Commit** your changes
```bash
git commit -m 'feat: add amazing feature'
```
6. **Push** to your branch
```bash
git push origin feature/amazing-feature
```
7. **Open** a Pull Request

Please ensure your PR:

- ✅ Passes all existing tests
- ✅ Includes tests for new functionality
- ✅ Follows the existing code style
- ✅ Updates documentation as needed

---

## 🆘 Support

---

## 📄 License

---

**[⬆ Back to Top](#-inventory-service)**

Made with ❤️ by the xshopai team

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/xshopai/inventory-service

Awesome Lists containing this project

README