{"id":48770371,"url":"https://github.com/xshopai/inventory-service","last_synced_at":"2026-04-13T09:46:07.829Z","repository":{"id":312053246,"uuid":"1045893782","full_name":"xshopai/inventory-service","owner":"xshopai","description":"Tracks stock levels, availability, and inventory updates.","archived":false,"fork":false,"pushed_at":"2026-02-27T14:52:32.000Z","size":581,"stargazers_count":1,"open_issues_count":8,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-27T18:44:59.892Z","etag":null,"topics":["flask","microservice","mysql","python","xshopai"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xshopai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-27T21:51:05.000Z","updated_at":"2026-02-27T14:52:36.000Z","dependencies_parsed_at":"2025-08-28T14:48:36.120Z","dependency_job_id":"b655071a-9c19-48ed-8a1f-075e0b7947bc","html_url":"https://github.com/xshopai/inventory-service","commit_stats":null,"previous_names":["aioutlet/inventory-service","xshopai/inventory-service"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/xshopai/inventory-service","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xshopai%2Finventory-service","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xshopai%2Finventory-service/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xshopai%2Finventory-service/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xshopai%2Finventory-service/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xshopai","download_url":"https://codeload.github.com/xshopai/inventory-service/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xshopai%2Finventory-service/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31746341,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-13T09:16:15.125Z","status":"ssl_error","status_checked_at":"2026-04-13T09:16:05.023Z","response_time":93,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["flask","microservice","mysql","python","xshopai"],"created_at":"2026-04-13T09:46:05.043Z","updated_at":"2026-04-13T09:46:07.823Z","avatar_url":"https://github.com/xshopai.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# 📦 Inventory Service\n\n**Enterprise-grade inventory management microservice for the xshopai e-commerce platform**\n\n[![Python](https://img.shields.io/badge/Python-3.11+-3776AB?style=for-the-badge\u0026logo=python\u0026logoColor=white)](https://python.org)\n[![Flask](https://img.shields.io/badge/Flask-3.0+-000000?style=for-the-badge\u0026logo=flask\u0026logoColor=white)](https://flask.palletsprojects.com)\n[![MySQL](https://img.shields.io/badge/MySQL-8.0+-4479A1?style=for-the-badge\u0026logo=mysql\u0026logoColor=white)](https://mysql.com)\n[![Dapr](https://img.shields.io/badge/Dapr-Enabled-0D597F?style=for-the-badge\u0026logo=dapr\u0026logoColor=white)](https://dapr.io)\n[![License](https://img.shields.io/badge/License-Proprietary-red?style=for-the-badge)](LICENSE)\n\n[Getting Started](#-getting-started) •\n[Documentation](#-documentation) •\n[API Reference](docs/PRD.md) •\n[Contributing](#-contributing)\n\n\u003c/div\u003e\n\n---\n\n## 🎯 Overview\n\nThe **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.\n\n---\n\n## ✨ Key Features\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\"\u003e\n\n### 📊 Stock Management\n\n- Real-time inventory tracking\n- Multi-variant product support\n- Low stock alerts \u0026 thresholds\n- Automatic stock reconciliation\n\n\u003c/td\u003e\n\u003ctd width=\"50%\"\u003e\n\n### 🔒 Reservation System\n\n- Time-limited stock reservations\n- Automatic expiration handling\n- Order processing integration\n- Concurrent access control\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\"\u003e\n\n### 📡 Event-Driven Architecture\n\n- CloudEvents 1.0 specification\n- Pub/sub messaging integration\n- Real-time inventory updates\n- Cross-service synchronization\n\n\u003c/td\u003e\n\u003ctd width=\"50%\"\u003e\n\n### 🛡️ Enterprise Security\n\n- JWT token authentication\n- Service-to-service tokens\n- Role-based access control\n- Complete audit trail\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n---\n\n## 🚀 Getting Started\n\n### Prerequisites\n\n- Python 3.11+\n- MySQL 8.0+\n- Docker \u0026 Docker Compose (optional)\n- Dapr CLI (for production-like setup)\n\n### Quick Start with Docker Compose\n\n```bash\n# Clone the repository\ngit clone https://github.com/xshopai/inventory-service.git\ncd inventory-service\n\n# Start all services (MySQL, service, etc.)\ndocker-compose up -d\n\n# Verify the service is healthy\ncurl http://localhost:8005/health\n```\n\n### Local Development Setup\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e🔧 Without Dapr (Simple Setup)\u003c/b\u003e\u003c/summary\u003e\n\n```bash\n# Create virtual environment\npython -m venv venv\nsource venv/bin/activate  # Windows: venv\\Scripts\\activate\n\n# Install dependencies\npip install -r requirements.txt\n\n# Set up environment variables\ncp .env.example .env\n# Edit .env with your configuration\n\n# Run database migrations\nflask db upgrade\n\n# Start the service\npython run.py\n```\n\n📖 See [Local Development Guide](docs/LOCAL_DEVELOPMENT.md) for detailed instructions.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e⚡ With Dapr (Production-like)\u003c/b\u003e\u003c/summary\u003e\n\n```bash\n# Ensure Dapr is initialized\ndapr init\n\n# Start with Dapr sidecar\ndapr run \\\n  --app-id inventory-service \\\n  --app-port 8005 \\\n  --dapr-http-port 3500 \\\n  --resources-path .dapr/components \\\n  --config .dapr/config.yaml \\\n  -- python run.py\n```\n\n\u003e **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.\n\n📖 See [Dapr Development Guide](docs/LOCAL_DEVELOPMENT_DAPR.md) for detailed instructions.\n\n\u003c/details\u003e\n\n---\n\n## 📚 Documentation\n\n| Document                                                         | Description                                          |\n| :--------------------------------------------------------------- | :--------------------------------------------------- |\n| 📘 [Local Development](docs/LOCAL_DEVELOPMENT.md)                | Step-by-step local setup without Dapr                |\n| ⚡ [Local Development with Dapr](docs/LOCAL_DEVELOPMENT_DAPR.md) | Local setup with full Dapr integration               |\n| ☁️ [Azure Container Apps](docs/ACA_DEPLOYMENT.md)                | Deploy to serverless containers with built-in Dapr   |\n| 📋 [Product Requirements](docs/PRD.md)                           | Complete API specification and business requirements |\n| 🏗️ [Architecture](docs/ARCHITECTURE.md)                          | System design, patterns, and data flows              |\n| 🔐 [Security](.github/SECURITY.md)                               | Security policies and vulnerability reporting        |\n\n---\n\n## 🧪 Testing\n\nWe maintain high code quality standards with comprehensive test coverage.\n\n```bash\n# Run all unit tests\npytest tests/unit/ -v\n\n# Run with coverage report\npytest --cov=src --cov-report=html --cov-report=term-missing\n\n# Run specific test file\npytest tests/unit/test_inventory_service.py -v\n\n# Run integration tests (requires running services)\npytest tests/integration/ -v\n```\n\n### Test Coverage\n\n| Metric        | Status               |\n| :------------ | :------------------- |\n| Unit Tests    | ✅ 33 passing        |\n| Code Coverage | ✅ 91.4%             |\n| Security Scan | ✅ 0 vulnerabilities |\n\n---\n\n## 🏗️ Project Structure\n\n```\ninventory-service/\n├── 📁 src/                       # Application source code\n│   ├── 📁 controllers/           # REST API endpoints\n│   ├── 📁 services/              # Business logic layer\n│   ├── 📁 repositories/          # Data access layer\n│   ├── 📁 models/                # SQLAlchemy models\n│   ├── 📁 messaging/             # Messaging abstraction (Dapr/ServiceBus/RabbitMQ)\n│   ├── 📁 middlewares/           # Authentication, logging, tracing\n│   └── 📁 utils/                 # Helper functions \u0026 utilities\n├── 📁 tests/                     # Test suite\n│   ├── 📁 unit/                  # Unit tests\n│   ├── 📁 integration/           # Integration tests\n│   └── 📁 e2e/                   # End-to-end tests\n├── 📁 migrations/                # Alembic database migrations\n├── 📁 .dapr/                     # Dapr configuration\n│   ├── 📁 components/            # Pub/sub, secrets, state stores\n│   └── 📄 config.yaml            # Dapr runtime configuration\n├── 📁 docs/                      # Documentation\n├── 📄 docker-compose.yml         # Local containerized environment\n├── 📄 Dockerfile                 # Production container image\n└── 📄 requirements.txt           # Python dependencies\n```\n\n---\n\n## 🔧 Technology Stack\n\n| Category          | Technology                                    |\n| :---------------- | :-------------------------------------------- |\n| 🐍 Runtime        | Python 3.11+                                  |\n| 🌐 Framework      | Flask 3.0+ with Flask-RESTX (OpenAPI/Swagger) |\n| 🗄️ Database       | MySQL 8.0+ with SQLAlchemy ORM                |\n| 📨 Messaging      | Dapr Pub/Sub, Azure Service Bus, RabbitMQ     |\n| 📋 Event Format   | CloudEvents 1.0 Specification                 |\n| 🔐 Authentication | JWT Tokens + Service-to-Service Tokens        |\n| 🧪 Testing        | pytest with coverage reporting                |\n| 📊 Observability  | Structured logging, distributed tracing       |\n\n---\n\n## ⚡ Quick Reference\n\n```bash\n# 🐳 Docker Compose\ndocker-compose up -d              # Start all services\ndocker-compose down               # Stop all services\ndocker-compose logs -f inventory  # View logs\n\n# 🐍 Local Development\npython run.py                     # Run without Dapr\nflask db upgrade                  # Apply migrations\nflask db migrate -m \"message\"     # Create migration\n\n# ⚡ Dapr Development\ndapr run --app-id inventory-service --app-port 8005 -- python run.py\n\n# 🧪 Testing\npytest tests/unit/ -v             # Run unit tests\npytest --cov=src                  # Run with coverage\n\n# 🔍 Health Check\ncurl http://localhost:8005/health\ncurl http://localhost:8005/health/ready\n```\n\n---\n\n## 🤝 Contributing\n\nWe welcome contributions! Please follow these steps:\n\n1. **Fork** the repository\n2. **Create** a feature branch\n   ```bash\n   git checkout -b feature/amazing-feature\n   ```\n3. **Write** tests for your changes\n4. **Run** the test suite\n   ```bash\n   pytest \u0026\u0026 black . \u0026\u0026 flake8\n   ```\n5. **Commit** your changes\n   ```bash\n   git commit -m 'feat: add amazing feature'\n   ```\n6. **Push** to your branch\n   ```bash\n   git push origin feature/amazing-feature\n   ```\n7. **Open** a Pull Request\n\nPlease ensure your PR:\n\n- ✅ Passes all existing tests\n- ✅ Includes tests for new functionality\n- ✅ Follows the existing code style\n- ✅ Updates documentation as needed\n\n---\n\n## 🆘 Support\n\n| Resource         | Link                                                                           |\n| :--------------- | :----------------------------------------------------------------------------- |\n| 🐛 Bug Reports   | [GitHub Issues](https://github.com/xshopai/inventory-service/issues)           |\n| 📖 Documentation | [docs/](docs/)                                                                 |\n| 📋 API Reference | [docs/PRD.md](docs/PRD.md)                                                     |\n| 💬 Discussions   | [GitHub Discussions](https://github.com/xshopai/inventory-service/discussions) |\n\n---\n\n## 📄 License\n\nThis project is part of the **xshopai** e-commerce platform.  \n© 2026 xshopai. All rights reserved.\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**[⬆ Back to Top](#-inventory-service)**\n\nMade with ❤️ by the xshopai team\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxshopai%2Finventory-service","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxshopai%2Finventory-service","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxshopai%2Finventory-service/lists"}