{"id":50622141,"url":"https://github.com/travelxml/distrios","last_synced_at":"2026-06-06T13:01:55.475Z","repository":{"id":357768033,"uuid":"1236087803","full_name":"TravelXML/DistriOS","owner":"TravelXML","description":"DistriCore is an API-first Distribution Management Platform for FMCG, CPG, FMCD, OTC Pharma and general distribution businesses, built with Java Spring Boot.","archived":false,"fork":false,"pushed_at":"2026-05-14T06:47:20.000Z","size":65059,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-14T08:29:21.966Z","etag":null,"topics":["dms","dms-development","retail-technology"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TravelXML.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"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":"2026-05-12T00:03:16.000Z","updated_at":"2026-05-14T06:47:37.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/TravelXML/DistriOS","commit_stats":null,"previous_names":["travelxml/distrios"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/TravelXML/DistriOS","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TravelXML%2FDistriOS","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TravelXML%2FDistriOS/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TravelXML%2FDistriOS/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TravelXML%2FDistriOS/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TravelXML","download_url":"https://codeload.github.com/TravelXML/DistriOS/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TravelXML%2FDistriOS/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33983046,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-06T02:00:07.033Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["dms","dms-development","retail-technology"],"created_at":"2026-06-06T13:01:54.521Z","updated_at":"2026-06-06T13:01:55.462Z","avatar_url":"https://github.com/TravelXML.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# RetailTech\n# DistriOS - DistriCore a DMS API\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eAPI-first Distribution Management System for FMCG, CPG, FMCD, OTC Pharma, rurban markets, and general distribution businesses.\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cem\u003eDistriCore - One platform for modern retail distribution.\u003c/em\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"Java\" src=\"https://img.shields.io/badge/Java-21%2B-blue\"\u003e\n  \u003cimg alt=\"Spring Boot\" src=\"https://img.shields.io/badge/Spring%20Boot-API%20Backend-brightgreen\"\u003e\n  \u003cimg alt=\"PostgreSQL\" src=\"https://img.shields.io/badge/PostgreSQL-Database-blue\"\u003e\n  \u003cimg alt=\"Redis\" src=\"https://img.shields.io/badge/Redis-Cache-red\"\u003e\n  \u003cimg alt=\"Docker\" src=\"https://img.shields.io/badge/Docker-Ready-blue\"\u003e\n  \u003cimg alt=\"OpenAPI\" src=\"https://img.shields.io/badge/OpenAPI-Swagger-orange\"\u003e\n  \u003cimg alt=\"Architecture\" src=\"https://img.shields.io/badge/Architecture-Modular%20Monolith-purple\"\u003e\n\u003c/p\u003e\n\n---\n\n## Overview\n\n**DistriOS** is the repository for **DistriCore API**, a modern, API-first **Distribution Management Platform** built for companies, distributors, stockists, dealers, retailers, field sales teams, warehouses, and multi-company distribution networks.\n\nIt is designed to support the complete distribution lifecycle:\n\n- Distributor Management System, also known as **DMS**\n- Sales Force Automation, also known as **SFA**\n- Retailer ordering and engagement APIs\n- Inventory and warehouse management\n- Product catalogue, UOM, HSN, pricing, tax, and schemes\n- Orders, invoices, claims, warranty, product recall, and loyalty\n- AI-powered recommendations, outlet pulse, route optimization, smart nudges, and analytics\n- ERP, tax, payment, webhook, SMS, WhatsApp, and notification integrations\n\nDistriCore is not designed only for FMCG. It is configurable for multiple industry verticals including **FMCG, CPG, FMCD, OTC Pharma, and general distribution**.\n\n---\n\n## SEO Keywords\n\n`Distribution Management System`, `DMS Software`, `Distributor Management System`, `FMCG DMS`, `CPG Distribution Software`, `FMCD Distribution Platform`, `OTC Pharma Distribution`, `Rurban Distribution`, `Sales Force Automation`, `Retailer App APIs`, `Inventory Management`, `Order Management`, `Scheme Management`, `Claims Management`, `Java Spring Boot REST API`, `API-first Platform`, `Multi-Tenant SaaS`, `Modular Monolith`.\n\n---\n\n## Why DistriCore?\n\nTraditional distribution systems are usually fragmented. Distributors manage orders in one place, inventory somewhere else, claims manually, schemes through spreadsheets, and sales teams through disconnected tools.\n\nDistriCore solves this by creating a unified API-first backend that can power:\n\n- Admin portals\n- Distributor portals\n- Retailer apps\n- SFA mobile apps\n- Supervisor dashboards\n- AI and analytics layers\n- ERP and external integrations\n\n---\n\n## What Is Rurban?\n\n**Rurban** means **Rural + Urban**.\n\nIn distribution and retail, rurban markets are semi-urban, small-town, and fast-growing rural markets that show urban-like demand but still have rural-style distribution challenges.\n\nExamples:\n\n- Tier 3 and Tier 4 cities\n- Large villages\n- Semi-urban belts\n- Rural markets near cities\n- Emerging retail clusters\n- Small-town distributor networks\n\nIn DMS context, a **rurban distribution platform** helps distributors manage sales, stock, orders, schemes, claims, and field operations across spread-out retail markets where internet connectivity, route discipline, stock visibility, and manual ordering are common challenges.\n\n---\n\n## Supported Industry Verticals\n\nDistriCore uses an `IndustryVertical` model so every company or tenant can configure its own business behavior.\n\n```java\npublic enum IndustryVertical {\n    FMCG,\n    CPG,\n    FMCD,\n    OTC_PHARMA,\n    GENERAL_DISTRIBUTION\n}\n```\n\n### FMCG / CPG\n\nFor fast-moving consumer goods and consumer packaged goods.\n\nKey capabilities:\n\n- SKU-based product management\n- UOM, pack size, case size\n- MRP, base price, price list, and margins\n- Primary and secondary sales\n- Distributor-retailer mapping\n- Beat planning and route sales\n- Schemes, claims, promotions, and loyalty\n- Optional batch and expiry tracking\n\n### FMCD\n\nFor fast-moving consumer durables and high-value channel sales.\n\nKey capabilities:\n\n- Serial number tracking\n- Warranty tracking\n- Dealer and channel partner management\n- Product installation status\n- Demo unit tracking\n- Replacement and warranty claims\n- High-value inventory visibility\n\n### OTC Pharma\n\nFor over-the-counter medicine and pharma distribution.\n\nKey capabilities:\n\n- Mandatory batch tracking\n- Mandatory expiry tracking\n- HSN and GST compliance\n- Distributor and retailer drug license support\n- Stockist, chemist, and channel mapping\n- Near-expiry and expired stock alerts\n- Product recall handling\n- Composition, manufacturer, and regulatory fields\n\n### General Distribution\n\nFor configurable B2B distribution models.\n\nKey capabilities:\n\n- Flexible product attributes\n- Custom inventory rules\n- Multi-company distributor operations\n- Generic pricing, order, claim, and reporting workflows\n\n---\n\n## Core Capabilities\n\n| Capability | Description |\n|---|---|\n| Multi-Tenant SaaS | Tenant isolation using `X-Tenant-Id` |\n| API-First Design | REST APIs under `/api/v1` with Swagger/OpenAPI |\n| DMS | Distributor, retailer, warehouse, order, invoice, claims |\n| SFA | Beat planning, visits, check-in/out, expenses, tasks |\n| Retailer App APIs | Product catalogue, cart, order, loyalty, complaints |\n| Inventory | Stock ledger, batch, expiry, serial number, damaged and reserved stock |\n| Pricing Engine | Price list, distributor pricing, retailer pricing, tax calculation |\n| Scheme Engine | Discounts, slabs, Buy X Get Y, simulations, explainability |\n| Claims | Damage, expiry, shortage, rate difference, warranty, replacement, recall |\n| OTC Pharma | Drug license, expiry alerts, recalls, composition and manufacturer data |\n| FMCD | Serial numbers, warranty, demo units, replacement flow |\n| AI Layer | Recommendations, outlet pulse, route optimization, smart nudges |\n| Analytics | Sales, distributor, retailer, product, scheme, claim and SFA reports |\n| Integrations | ERP, tax validation, payment callbacks, webhooks, notifications |\n\n---\n\n## Technology Stack\n\n| Layer | Technology |\n|---|---|\n| Language | Java 21+ |\n| Framework | Spring Boot |\n| API | REST, OpenAPI, Swagger UI |\n| Security | Spring Security, JWT, RBAC |\n| Database | PostgreSQL |\n| Cache | Redis |\n| ORM | Spring Data JPA / Hibernate |\n| Migration | Flyway |\n| Validation | Jakarta Bean Validation |\n| Testing | JUnit 5, MockMvc, Testcontainers |\n| Build | Maven |\n| Container | Docker, Docker Compose |\n| Future Events | Kafka / RabbitMQ |\n| Observability | OpenTelemetry, Prometheus, Grafana |\n| Search | Elasticsearch / OpenSearch |\n| Storage | Object storage for attachments |\n\n---\n\n## Architecture\n\nDistriCore starts as a **modular monolith** with strong domain boundaries.\n\nThis keeps development simple and fast in the early stage while keeping the codebase ready for future microservice extraction.\n\n```text\nFrontend / Consumers\n  ├── Admin Portal\n  ├── Distributor Portal\n  ├── Retailer Mobile App\n  ├── SFA Mobile App\n  ├── Supervisor Dashboard\n  ├── ERP Systems\n  └── AI / Analytics Services\n\nAPI Layer\n  ├── REST APIs\n  ├── Swagger / OpenAPI\n  ├── JWT Security\n  ├── RBAC\n  ├── Tenant Filter\n  ├── Correlation ID Filter\n  └── Idempotency Support\n\nDistriCore Backend\n  ├── Common\n  ├── Identity / Security\n  ├── Tenant / Organization\n  ├── Distributor\n  ├── Retailer\n  ├── Product\n  ├── Pricing\n  ├── Inventory\n  ├── Order\n  ├── Invoice\n  ├── Scheme\n  ├── Claim\n  ├── Warranty\n  ├── Product Recall\n  ├── SFA\n  ├── Retailer App\n  ├── Loyalty\n  ├── Complaint\n  ├── Notification\n  ├── Analytics\n  ├── AI\n  └── Integration\n\nData / Infra\n  ├── PostgreSQL\n  ├── Redis\n  ├── Flyway\n  ├── Docker\n  ├── Optional Kafka / RabbitMQ\n  ├── Optional Object Storage\n  └── Optional Search Index\n```\n\n---\n\n## Project Structure\n\n```text\nDistriOS/\n  ├── src/\n  │   ├── main/\n  │   │   ├── java/com/districore/platform/\n  │   │   │   ├── DistriCoreApplication.java\n  │   │   │   ├── common/\n  │   │   │   ├── security/\n  │   │   │   ├── identity/\n  │   │   │   ├── tenant/\n  │   │   │   ├── organization/\n  │   │   │   ├── distributor/\n  │   │   │   ├── retailer/\n  │   │   │   ├── product/\n  │   │   │   ├── pricing/\n  │   │   │   ├── inventory/\n  │   │   │   ├── order/\n  │   │   │   ├── invoice/\n  │   │   │   ├── scheme/\n  │   │   │   ├── claim/\n  │   │   │   ├── warranty/\n  │   │   │   ├── recall/\n  │   │   │   ├── sfa/\n  │   │   │   ├── retailerapp/\n  │   │   │   ├── loyalty/\n  │   │   │   ├── complaint/\n  │   │   │   ├── notification/\n  │   │   │   ├── analytics/\n  │   │   │   ├── ai/\n  │   │   │   └── integration/\n  │   │   └── resources/\n  │   │       ├── application.yml\n  │   │       ├── application-local.yml\n  │   │       └── db/migration/\n  │   │           ├── V1__initial_schema.sql\n  │   │           └── V2__seed_master_data.sql\n  │   └── test/\n  ├── Dockerfile\n  ├── docker-compose.yml\n  ├── pom.xml\n  └── README.md\n```\n\n---\n\n## Domain Modules\n\n### Common\n\nShared platform infrastructure:\n\n- API response wrapper\n- Global exception handling\n- Error response structure\n- Base entity and tenant-aware entity\n- Audit fields\n- Pagination helpers\n- Correlation ID filter\n- Idempotency support\n- Common enums and constants\n\n### Identity and Security\n\nAuthentication and authorization:\n\n- Users\n- Roles\n- Permissions\n- JWT login\n- Refresh token\n- Logout\n- Password hashing\n- Role-based access control\n- Method-level authorization\n\n### Tenant and Organization\n\nMulti-company and business hierarchy:\n\n- Company\n- Business unit\n- Branch\n- Region\n- Territory\n- Route\n- Beat\n- Industry configuration\n\n### Distributor\n\nDistributor lifecycle management:\n\n- Distributor onboarding\n- Distributor branches\n- Credit limit\n- Territory mapping\n- Sales team mapping\n- OTC pharma drug license support\n- Performance summary\n\n### Retailer\n\nRetailer lifecycle management:\n\n- Retailer onboarding\n- Retailer KYC\n- Category and channel\n- Geo-location\n- Credit limit\n- Distributor mapping\n- Beat mapping\n- Ledger summary\n- OTC pharma drug license support\n\n### Product\n\nMulti-industry product master:\n\n- SKU\n- Brand\n- Category\n- Sub-category\n- UOM\n- HSN code\n- GST classification\n- Pack size\n- Case size\n- Barcode\n- Batch, expiry, serial number, warranty flags\n- Composition\n- Manufacturer\n- Regulatory category\n\n### Pricing\n\nPricing and margin logic:\n\n- Price lists\n- Price list items\n- Distributor-specific pricing\n- Retailer-specific pricing\n- Region-specific pricing\n- Effective date pricing\n- Price calculation API\n\n### Inventory\n\nStock and warehouse control:\n\n- Warehouse / godown\n- Stock in and stock out\n- Stock adjustment\n- Batch-wise stock\n- Expiry-wise stock\n- Serial-number-wise stock\n- Damaged stock\n- Expired stock\n- Reserved stock\n- Available stock\n- Low-stock alerts\n- Near-expiry alerts\n- Product recall stock impact\n\n### Order\n\nOrder lifecycle:\n\n- Order creation\n- Retailer and distributor validation\n- Product validation\n- Price calculation\n- Scheme application\n- Inventory reservation\n- Confirmation\n- Dispatch\n- Delivery\n- Status history\n\n### Invoice\n\nInvoice and tax:\n\n- Invoice generation from order\n- Invoice line items\n- GST calculation\n- CGST / SGST / IGST\n- HSN-wise tax summary\n- Invoice cancellation\n- Credit note and debit note placeholders\n\n### Scheme\n\nPromotion and scheme engine:\n\n- Percentage discount\n- Flat discount\n- Buy X Get Y\n- Slab discounts\n- Product, brand, category, distributor, region, and retailer-level schemes\n- Scheme simulation\n- Explainable scheme calculation\n\n### Claim\n\nClaims and approval workflow:\n\n- Damage claim\n- Expiry claim\n- Scheme claim\n- Rate difference claim\n- Shortage claim\n- Return claim\n- Warranty claim\n- Replacement claim\n- Recall claim\n- Attachments metadata\n- Approval history\n\n### SFA\n\nSales Force Automation:\n\n- Beat plan\n- Today route\n- Check-in\n- Check-out\n- Retailer visit\n- Order capture\n- Expense management\n- Task management\n- Supervisor dashboard\n- Van sales placeholder\n\n### Retailer App\n\nRetailer self-service:\n\n- Home\n- Product catalogue\n- Recommended products\n- Applicable schemes\n- Cart\n- Order placement\n- Order tracking\n- Complaints\n- Loyalty summary\n\n### AI\n\nAI adapter layer:\n\n- Product recommendations\n- Outlet pulse\n- Route optimization\n- Scheme simulation insights\n- Sales analyzer\n- Target disaggregation\n- Smart nudges\n- Supervisor insights\n\n### Integration\n\nExternal system connectivity:\n\n- ERP order push\n- ERP invoice push\n- Tax validation\n- Payment callback\n- Webhook management\n- Event publishing placeholder\n\n---\n\n## Key Domain Terms\n\n### UOM\n\n**Unit of Measure** - how a product is measured, stocked, or sold.\n\nExamples:\n\n```text\nPCS, KG, LTR, BOX, CASE, DOZEN\n```\n\n### HSN Code\n\n**Harmonized System of Nomenclature** - tax classification code used for GST and invoicing.\n\n### Pack Size\n\nQuantity inside one sellable unit.\n\nExamples:\n\n```text\n500 ml bottle\n1 kg packet\n100 tablet strip\n```\n\n### Case Size\n\nNumber of sellable units inside one carton/case.\n\nExamples:\n\n```text\n1 case = 24 bottles\n1 carton = 12 packets\n```\n\n---\n\n## API Design Principles\n\n- All APIs are versioned under `/api/v1`\n- REST-first design\n- OpenAPI / Swagger documentation\n- DTO-based request and response models\n- No direct JPA entity exposure\n- Consistent success and error responses\n- Multi-tenant isolation using `X-Tenant-Id`\n- Correlation ID for traceability\n- Idempotency key support for critical writes\n- Pagination for list APIs\n- RBAC and JWT security\n- Service-layer business logic\n- Repository access only inside service layer\n- `BigDecimal` for money\n- Flyway for schema migrations\n\n---\n\n## Standard API Response\n\n### Success Response\n\n```json\n{\n  \"success\": true,\n  \"message\": \"Operation completed successfully\",\n  \"data\": {},\n  \"correlationId\": \"2ff7a8c9-8a80-4712-b6e8-134ce8e99dd0\"\n}\n```\n\n### Error Response\n\n```json\n{\n  \"timestamp\": \"2026-05-12T10:30:00Z\",\n  \"status\": 400,\n  \"error\": \"Bad Request\",\n  \"message\": \"Invalid request payload\",\n  \"path\": \"/api/v1/orders\",\n  \"correlationId\": \"2ff7a8c9-8a80-4712-b6e8-134ce8e99dd0\"\n}\n```\n\n---\n\n## Important Headers\n\n| Header | Required | Purpose |\n|---|---:|---|\n| `Authorization` | Yes | Bearer JWT token |\n| `X-Tenant-Id` | Yes for tenant APIs | Tenant/company isolation |\n| `X-Correlation-Id` | Optional | Request tracing |\n| `Idempotency-Key` | Required for selected write APIs | Prevent duplicate writes |\n\n---\n\n## API Endpoint Summary\n\n### Auth\n\n```http\nPOST /api/v1/auth/register\nPOST /api/v1/auth/login\nPOST /api/v1/auth/refresh-token\nPOST /api/v1/auth/logout\nGET  /api/v1/auth/me\n```\n\n### Users\n\n```http\nPOST   /api/v1/users\nGET    /api/v1/users\nGET    /api/v1/users/{id}\nPUT    /api/v1/users/{id}\nPATCH  /api/v1/users/{id}/status\nPOST   /api/v1/users/{id}/roles\n```\n\n### Industry Config\n\n```http\nPOST /api/v1/industry-config\nGET  /api/v1/industry-config\nGET  /api/v1/industry-config/{industryVertical}\nPUT  /api/v1/industry-config/{industryVertical}\n```\n\n### Distributor\n\n```http\nPOST   /api/v1/distributors\nGET    /api/v1/distributors\nGET    /api/v1/distributors/{id}\nPUT    /api/v1/distributors/{id}\nPATCH  /api/v1/distributors/{id}/status\nPOST   /api/v1/distributors/{id}/branches\nGET    /api/v1/distributors/{id}/branches\nPOST   /api/v1/distributors/{id}/credit-limit\nPOST   /api/v1/distributors/{id}/drug-license\nGET    /api/v1/distributors/{id}/performance-summary\n```\n\n### Retailer\n\n```http\nPOST   /api/v1/retailers\nGET    /api/v1/retailers\nGET    /api/v1/retailers/{id}\nPUT    /api/v1/retailers/{id}\nPATCH  /api/v1/retailers/{id}/status\nPOST   /api/v1/retailers/{id}/kyc\nPOST   /api/v1/retailers/{id}/drug-license\nGET    /api/v1/retailers/{id}/ledger\nGET    /api/v1/retailers/{id}/orders\nGET    /api/v1/retailers/{id}/schemes\nGET    /api/v1/retailers/{id}/loyalty\n```\n\n### Product\n\n```http\nPOST   /api/v1/products\nGET    /api/v1/products\nGET    /api/v1/products/{id}\nPUT    /api/v1/products/{id}\nPATCH  /api/v1/products/{id}/status\nPOST   /api/v1/products/{productId}/serial-numbers\nGET    /api/v1/products/{productId}/serial-numbers\nPOST   /api/v1/product-categories\nGET    /api/v1/product-categories\nPOST   /api/v1/brands\nGET    /api/v1/brands\nPOST   /api/v1/uoms\nGET    /api/v1/uoms\nPOST   /api/v1/hsn-codes\nGET    /api/v1/hsn-codes\n```\n\n### Pricing\n\n```http\nPOST   /api/v1/price-lists\nGET    /api/v1/price-lists\nGET    /api/v1/price-lists/{id}\nPOST   /api/v1/price-lists/{id}/items\nGET    /api/v1/products/{productId}/prices\nGET    /api/v1/retailers/{retailerId}/applicable-prices\nPOST   /api/v1/pricing/calculate\n```\n\n### Inventory\n\n```http\nGET    /api/v1/inventory\nGET    /api/v1/inventory/warehouses/{warehouseId}\nPOST   /api/v1/inventory/stock-in\nPOST   /api/v1/inventory/stock-out\nPOST   /api/v1/inventory/adjustments\nGET    /api/v1/inventory/transactions\nGET    /api/v1/inventory/low-stock\nGET    /api/v1/inventory/near-expiry\nGET    /api/v1/inventory/expired-stock\nGET    /api/v1/inventory/products/{productId}/availability\n```\n\n### Order\n\n```http\nPOST   /api/v1/orders\nGET    /api/v1/orders\nGET    /api/v1/orders/{id}\nPATCH  /api/v1/orders/{id}/confirm\nPATCH  /api/v1/orders/{id}/cancel\nPATCH  /api/v1/orders/{id}/dispatch\nPATCH  /api/v1/orders/{id}/deliver\nGET    /api/v1/orders/{id}/status-history\n```\n\n### Invoice\n\n```http\nPOST   /api/v1/invoices/from-order/{orderId}\nGET    /api/v1/invoices\nGET    /api/v1/invoices/{id}\nGET    /api/v1/invoices/{id}/tax-summary\nPATCH  /api/v1/invoices/{id}/cancel\n```\n\n### Scheme\n\n```http\nPOST   /api/v1/schemes\nGET    /api/v1/schemes\nGET    /api/v1/schemes/{id}\nPUT    /api/v1/schemes/{id}\nPATCH  /api/v1/schemes/{id}/status\nPOST   /api/v1/schemes/simulate\nPOST   /api/v1/orders/{orderId}/apply-schemes\nGET    /api/v1/retailers/{retailerId}/eligible-schemes\n```\n\n### Claim\n\n```http\nPOST   /api/v1/claims\nGET    /api/v1/claims\nGET    /api/v1/claims/{id}\nPATCH  /api/v1/claims/{id}/approve\nPATCH  /api/v1/claims/{id}/reject\nPOST   /api/v1/claims/{id}/attachments\nGET    /api/v1/claims/reports/summary\n```\n\n### Warranty\n\n```http\nPOST /api/v1/warranties\nGET  /api/v1/warranties/{serialNumber}\nPOST /api/v1/warranty-claims\n```\n\n### Product Recall\n\n```http\nPOST  /api/v1/product-recalls\nGET   /api/v1/product-recalls\nGET   /api/v1/product-recalls/{id}\nPATCH /api/v1/product-recalls/{id}/close\n```\n\n### SFA\n\n```http\nGET    /api/v1/sfa/my-beats\nGET    /api/v1/sfa/today-route\nPOST   /api/v1/sfa/check-in\nPOST   /api/v1/sfa/check-out\nPOST   /api/v1/sfa/retailer-visit\nPOST   /api/v1/sfa/orders\nPOST   /api/v1/sfa/expenses\nGET    /api/v1/sfa/tasks\nPATCH  /api/v1/sfa/tasks/{id}/complete\nGET    /api/v1/sfa/supervisor/dashboard\n```\n\n### Retailer App\n\n```http\nGET    /api/v1/retailer-app/home\nGET    /api/v1/retailer-app/products\nGET    /api/v1/retailer-app/recommended-products\nGET    /api/v1/retailer-app/schemes\nPOST   /api/v1/retailer-app/cart/items\nGET    /api/v1/retailer-app/cart\nPOST   /api/v1/retailer-app/orders\nGET    /api/v1/retailer-app/orders\nGET    /api/v1/retailer-app/orders/{id}\nPOST   /api/v1/retailer-app/complaints\nGET    /api/v1/retailer-app/loyalty\n```\n\n### Loyalty\n\n```http\nPOST   /api/v1/loyalty/accounts\nGET    /api/v1/loyalty/accounts/{retailerId}\nPOST   /api/v1/loyalty/earn\nPOST   /api/v1/loyalty/redeem\nGET    /api/v1/loyalty/transactions\n```\n\n### Complaint\n\n```http\nPOST   /api/v1/complaints\nGET    /api/v1/complaints\nGET    /api/v1/complaints/{id}\nPATCH  /api/v1/complaints/{id}/assign\nPATCH  /api/v1/complaints/{id}/resolve\nPATCH  /api/v1/complaints/{id}/close\n```\n\n### AI\n\n```http\nGET    /api/v1/ai/product-recommendations?retailerId=\nGET    /api/v1/ai/outlet-pulse/{retailerId}\nPOST   /api/v1/ai/route-optimization\nPOST   /api/v1/ai/scheme-simulation\nGET    /api/v1/ai/sales-analyzer\nPOST   /api/v1/ai/target-disaggregation\nGET    /api/v1/ai/smart-nudges\nGET    /api/v1/ai/supervisor-insights\n```\n\n### Analytics\n\n```http\nGET /api/v1/analytics/sales-summary\nGET /api/v1/analytics/distributor-performance\nGET /api/v1/analytics/retailer-performance\nGET /api/v1/analytics/product-performance\nGET /api/v1/analytics/scheme-performance\nGET /api/v1/analytics/stock-movement\nGET /api/v1/analytics/sfa-productivity\nGET /api/v1/analytics/claims-summary\n```\n\n### Integration\n\n```http\nPOST /api/v1/webhooks\nGET  /api/v1/webhooks\nPOST /api/v1/integrations/erp/push-order\nPOST /api/v1/integrations/erp/push-invoice\nPOST /api/v1/integrations/tax/validate-gstin\nPOST /api/v1/integrations/payment/callback\n```\n\n---\n\n## Order Flow\n\n```text\n1. Create order\n2. Validate retailer\n3. Validate distributor\n4. Validate products\n5. Calculate price\n6. Apply eligible schemes\n7. Reserve inventory\n8. Confirm order\n9. Generate invoice\n10. Dispatch\n11. Deliver\n12. Maintain order status history\n```\n\nOrder sources:\n\n```text\nADMIN\nDISTRIBUTOR\nRETAILER_APP\nSFA_APP\n```\n\n---\n\n## Inventory Rules\n\nEvery stock movement must create an `InventoryTransaction`.\n\nStock types:\n\n```text\nAVAILABLE\nRESERVED\nDAMAGED\nEXPIRED\nIN_TRANSIT\nDEMO\nRETURNED\n```\n\nTransaction types:\n\n```text\nSTOCK_IN\nSTOCK_OUT\nADJUSTMENT\nRESERVATION\nRELEASE_RESERVATION\nDISPATCH\nRETURN\nDAMAGE\nEXPIRY\nRECALL\nWARRANTY_REPLACEMENT\n```\n\n---\n\n## Scheme Engine\n\nSupported scheme types:\n\n```text\nPERCENTAGE_DISCOUNT\nFLAT_DISCOUNT\nBUY_X_GET_Y\nSLAB_DISCOUNT\n```\n\nScheme simulation response should include:\n\n- Original order value\n- Discount value\n- Free items\n- Final order value\n- Applied schemes\n- Explanation of why each scheme was applied\n\n---\n\n## Pricing Engine\n\nPricing calculation should consider:\n\n- Base price\n- Price list by distributor or region\n- Retailer-specific override\n- Distributor-specific override\n- GST or tax calculation\n- Final price\n\n---\n\n## GST / Tax Model\n\nDistriCore supports GST-like tax configuration.\n\nTax components:\n\n```text\nCGST\nSGST\nIGST\n```\n\nTax summary:\n\n- Product-level tax\n- HSN-wise tax summary\n- Invoice-level GST summary\n\n---\n\n## Events\n\nDistriCore can publish or prepare internal events for:\n\n```text\nDistributorCreated\nRetailerCreated\nProductCreated\nPriceUpdated\nInventoryAdjusted\nOrderCreated\nOrderConfirmed\nOrderCancelled\nInvoiceGenerated\nClaimSubmitted\nClaimApproved\nSchemeApplied\nSalesVisitCompleted\nRetailerInactiveDetected\nProductRecallCreated\nNearExpiryDetected\nWarrantyClaimSubmitted\n```\n\nInitial versions can keep events as internal application events or outbox records.\n\n---\n\n## Getting Started\n\n### Prerequisites\n\nInstall:\n\n- Java 21+\n- Maven 3.6+\n- Docker\n- Docker Compose\n- PostgreSQL 15+\n- Redis 7+\n\n---\n\n## Clone and Build\n\n```bash\ngit clone https://github.com/TravelXML/DistriOS.git\ncd DistriOS\nmvn clean package\n```\n\n---\n\n## Run With Docker Compose\n\n```bash\ndocker compose up --build\n```\n\nApplication:\n\n```text\nhttp://localhost:8080\n```\n\nSwagger UI:\n\n```text\nhttp://localhost:8080/swagger-ui/index.html\n```\n\nOpenAPI JSON:\n\n```text\nhttp://localhost:8080/v3/api-docs\n```\n\n---\n\n## Run Locally\n\nStart PostgreSQL and Redis first.\n\nThen run:\n\n```bash\nmvn clean spring-boot:run\n```\n\nOr run the packaged JAR:\n\n```bash\njava -jar target/districore-api-0.1.0.jar\n```\n\nRun with test profile:\n\n```bash\njava -jar target/districore-api-0.1.0.jar --spring.profiles.active=test\n```\n\n---\n\n## Docker Commands\n\n```bash\ndocker compose up -d\ndocker compose ps\ndocker compose logs -f app\ndocker compose down\n```\n\nReset local environment:\n\n```bash\ndocker compose down -v\ndocker compose up -d\n```\n\n---\n\n## Environment Variables\n\nExample local configuration:\n\n```env\nSPRING_PROFILES_ACTIVE=local\n\nDB_HOST=localhost\nDB_PORT=5432\nDB_NAME=districore\nDB_USERNAME=districore\nDB_PASSWORD=districore\n\nREDIS_HOST=localhost\nREDIS_PORT=6379\n\nJWT_SECRET=change-this-secret\nJWT_EXPIRATION_MINUTES=60\nJWT_REFRESH_EXPIRATION_DAYS=7\n```\n\n---\n\n## Default Credentials\n\n```text\nUsername: admin\nPassword: Admin123!\nTenant ID: default\n```\n\nChange the default password before production use.\n\n---\n\n## Sample API Calls\n\n### Login\n\n```bash\ncurl -X POST http://localhost:8080/api/v1/auth/login   -H \"Content-Type: application/json\"   -H \"X-Tenant-Id: default\"   -d '{\n    \"username\": \"admin\",\n    \"password\": \"Admin123!\"\n  }'\n```\n\n### Create Distributor\n\n```bash\ncurl -X POST http://localhost:8080/api/v1/distributors   -H \"Content-Type: application/json\"   -H \"Authorization: Bearer \u003ctoken\u003e\"   -H \"X-Tenant-Id: default\"   -d '{\n    \"code\": \"DIST-BLR-001\",\n    \"name\": \"Bangalore Central Distributor\",\n    \"gstin\": \"29ABCDE1234F1Z5\",\n    \"pan\": \"ABCDE1234F\",\n    \"contactPerson\": \"Ramesh Kumar\",\n    \"mobile\": \"9876543210\",\n    \"email\": \"ramesh@example.com\",\n    \"city\": \"Bengaluru\",\n    \"state\": \"Karnataka\",\n    \"pincode\": \"560066\",\n    \"country\": \"India\",\n    \"creditLimit\": 5000000\n  }'\n```\n\n### Create Product\n\n```bash\ncurl -X POST http://localhost:8080/api/v1/products   -H \"Content-Type: application/json\"   -H \"Authorization: Bearer \u003ctoken\u003e\"   -H \"X-Tenant-Id: default\"   -d '{\n    \"skuCode\": \"COKE-750ML\",\n    \"productName\": \"Coke 750 ML Bottle\",\n    \"industryVertical\": \"FMCG\",\n    \"uom\": \"PCS\",\n    \"packSize\": \"750\",\n    \"packSizeUom\": \"ML\",\n    \"caseSize\": 24,\n    \"hsnCode\": \"22021010\",\n    \"gstRate\": 18,\n    \"mrp\": 45.00,\n    \"basePrice\": 36.00,\n    \"barcode\": \"890000000001\",\n    \"batchRequired\": false,\n    \"expiryRequired\": false,\n    \"serialNumberRequired\": false,\n    \"warrantyRequired\": false\n  }'\n```\n\n### Stock In\n\n```bash\ncurl -X POST http://localhost:8080/api/v1/inventory/stock-in   -H \"Content-Type: application/json\"   -H \"Authorization: Bearer \u003ctoken\u003e\"   -H \"X-Tenant-Id: default\"   -H \"Idempotency-Key: stock-in-001\"   -d '{\n    \"warehouseId\": \"\u003cwarehouse-id\u003e\",\n    \"productId\": \"\u003cproduct-id\u003e\",\n    \"quantity\": 1000,\n    \"stockType\": \"AVAILABLE\",\n    \"batchNumber\": \"BATCH-001\",\n    \"expiryDate\": \"2027-12-31\",\n    \"remarks\": \"Initial stock\"\n  }'\n```\n\n### Create Order\n\n```bash\ncurl -X POST http://localhost:8080/api/v1/orders   -H \"Content-Type: application/json\"   -H \"Authorization: Bearer \u003ctoken\u003e\"   -H \"X-Tenant-Id: default\"   -H \"Idempotency-Key: order-001\"   -d '{\n    \"retailerId\": \"\u003cretailer-id\u003e\",\n    \"distributorId\": \"\u003cdistributor-id\u003e\",\n    \"orderSource\": \"RETAILER_APP\",\n    \"items\": [\n      {\n        \"productId\": \"\u003cproduct-id\u003e\",\n        \"quantity\": 10,\n        \"uom\": \"CASE\"\n      }\n    ],\n    \"remarks\": \"Urgent delivery required\"\n  }'\n```\n\n### Scheme Simulation\n\n```bash\ncurl -X POST http://localhost:8080/api/v1/schemes/simulate   -H \"Content-Type: application/json\"   -H \"Authorization: Bearer \u003ctoken\u003e\"   -H \"X-Tenant-Id: default\"   -d '{\n    \"retailerId\": \"\u003cretailer-id\u003e\",\n    \"distributorId\": \"\u003cdistributor-id\u003e\",\n    \"items\": [\n      {\n        \"productId\": \"\u003cproduct-id\u003e\",\n        \"quantity\": 20\n      }\n    ]\n  }'\n```\n\n---\n\n## Database Migrations\n\nDistriCore uses Flyway.\n\nCore migration files:\n\n```text\nV1__initial_schema.sql\nV2__seed_master_data.sql\n```\n\nSeed data should include:\n\n- Company\n- Roles\n- Permissions\n- Admin user\n- Distributor\n- Retailer\n- Product categories\n- Brands\n- UOMs\n- HSN codes\n- Sample FMCG product\n- Sample FMCD product\n- Sample OTC pharma product\n- Warehouse\n- Inventory\n- Price list\n- Scheme\n\n---\n\n## Testing\n\nRun tests:\n\n```bash\nmvn test\n```\n\nRecommended coverage:\n\n- Auth login\n- Distributor creation\n- Retailer creation\n- Product creation\n- Stock-in\n- Order creation\n- Scheme simulation\n- Invoice generation\n- Claim submission\n- Warranty creation\n- Near-expiry inventory query\n- Product recall creation\n\n---\n\n## Build\n\n```bash\nmvn clean package\n```\n\nRun packaged JAR:\n\n```bash\njava -jar target/districore-api-0.1.0.jar\n```\n\n---\n\n## What Is Fully Implemented\n\n- Core multi-tenant domain design\n- API-first modular monolith structure\n- Auth and RBAC foundations\n- Industry configuration model\n- Distributor and retailer lifecycle APIs\n- Product master, category, brand, UOM, HSN support\n- Pricing and invoice foundation\n- Inventory transaction capture\n- Order lifecycle and status history\n- Claims, warranty, product recall, and complaint structure\n- Loyalty account management\n- Flyway migration and seed data structure\n- Docker Compose support\n- Swagger UI support\n\n---\n\n## Structurally Ready as Placeholder\n\n- AI adapter APIs\n- ERP integration hooks\n- Payment callback integration\n- SMS, WhatsApp, and email notification adapters\n- Advanced analytics\n- Advanced pricing overrides\n- Advanced scheme engine\n- Attachment and object storage\n- Outbox pattern and event streaming\n- Advanced audit and user activity trails\n\n---\n\n## Roadmap\n\n### Phase 1 - Core DMS\n\n- Auth and RBAC\n- Company and tenant setup\n- Distributor onboarding\n- Retailer onboarding\n- Product master\n- UOM, HSN, brand, category\n- Inventory stock-in\n- Order creation\n- Basic pricing\n- Basic invoice\n\n### Phase 2 - Commercial Engine\n\n- Price list\n- Tax engine\n- Scheme engine\n- Claim management\n- Ledger summaries\n- Credit limit\n- Order confirmation and dispatch\n\n### Phase 3 - SFA and Retailer App\n\n- Beat planning\n- Route planning\n- Field check-in/out\n- Retailer visit\n- Salesman order capture\n- Retailer catalogue\n- Cart and self-ordering\n- Loyalty and complaint management\n\n### Phase 4 - Industry-Specific Depth\n\n- FMCD serial number and warranty\n- OTC pharma batch, expiry, and recall\n- Rurban distributor workflows\n- Multi-company distributor operations\n- Advanced warehouse and return flows\n\n### Phase 5 - AI and Analytics\n\n- Product recommender\n- Outlet pulse\n- Route optimization\n- Sales analyzer\n- Target disaggregation\n- Scheme simulation insights\n- Smart nudges\n- Supervisor insights\n\n### Phase 6 - Enterprise Scale\n\n- Kafka / RabbitMQ\n- Outbox pattern\n- OpenTelemetry\n- Prometheus and Grafana\n- Elasticsearch / OpenSearch\n- Object storage\n- API gateway\n- Multi-region deployment\n\n---\n\n## Future Microservice Split Strategy\n\nThe modular monolith can later be split into independent services.\n\nSuggested service split:\n\n```text\nidentity-service\ntenant-service\nproduct-service\npricing-service\ninventory-service\norder-service\ninvoice-service\nscheme-service\nclaim-service\nsfa-service\nretailer-app-service\nloyalty-service\nnotification-service\nanalytics-service\nai-service\nintegration-service\n```\n\nRecommended extraction order:\n\n1. Identity and tenant\n2. Product and pricing\n3. Inventory\n4. Order and invoice\n5. Scheme and claim\n6. SFA and retailer app\n7. Analytics and AI\n8. Integration and notification\n\n---\n\n## Production Readiness Checklist\n\nBefore production:\n\n- Replace default admin password\n- Use a strong JWT secret\n- Enforce HTTPS\n- Restrict CORS\n- Validate tenant isolation\n- Enforce RBAC at API and method level\n- Add database indexes\n- Enable slow query monitoring\n- Enable audit logs\n- Configure backup and restore\n- Configure Redis memory limits\n- Add rate limiting\n- Add API gateway\n- Add structured logging with correlation ID\n- Enable OpenTelemetry\n- Scan Docker images\n- Move secrets to secret manager\n- Review Flyway migrations\n- Encrypt sensitive data where required\n\n---\n\n## Contributing\n\n1. Follow the modular architecture.\n2. Keep APIs versioned under `/api/v1`.\n3. Use DTOs for all request and response models.\n4. Write tests for new features.\n5. Update Swagger/OpenAPI documentation.\n6. Maintain backward compatibility.\n7. Use consistent error handling.\n8. Keep tenant isolation in mind for every business query.\n\n---\n\n## Maintainer\n\n**DistriCore Platform Team**\nastarupcto@gmail.com\n\nRepository: `TravelXML/DistriOS`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftravelxml%2Fdistrios","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftravelxml%2Fdistrios","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftravelxml%2Fdistrios/lists"}