SupplyBoost is an educational platform demonstrating enterprise-grade supply chain management through a distributed microservices architecture. This project serves as a comprehensive learning resource for modern software engineering practices, cloud-native patterns, and real-world system design challenges.
Project Status: ✅ Phase 3 Complete - Production-ready microservices platform with comprehensive observability, security, and deployment automation.
- Overview
- Architecture
- Features
- Technology Stack
- Getting Started
- Project Structure
- Development Roadmap
- Contributing
- Documentation
- License
SupplyBoost bridges the gap between theoretical knowledge and practical implementation of distributed systems. While countless resources teach microservices, event-driven architecture, and cloud technologies in isolation, few demonstrate how these patterns work together in a cohesive, production-like system.
This project aims to:
- Provide a realistic, non-trivial example of microservices architecture
- Demonstrate modern software engineering practices and patterns
- Serve as a learning platform for developers transitioning to distributed systems
- Showcase the full lifecycle: design → development → deployment → operations
- Mid-level developers seeking hands-on experience with microservices
- DevOps engineers exploring containerization and orchestration
- Architecture enthusiasts studying system design patterns
- Students and educators looking for real-world examples beyond "todo apps"
Unlike toy applications, SupplyBoost tackles real complexity:
- Multiple business domains: Identity, catalog, orders, inventory, payments, shipping, accounting
- Distributed transactions: Saga pattern for cross-service workflows
- Event-driven architecture: Asynchronous communication via Kafka
- Production-ready practices: Monitoring, logging, tracing, security, testing
SupplyBoost follows a microservices architecture with event-driven patterns.
┌─────────────┐ ┌──────────────┐ ┌────────────┐
│ Web UI │────────▶│ API Gateway │────────▶│ Services │
│ (Vue.js) │ │ (Spring) │ │ (9 µsvcs) │
└─────────────┘ └──────────────┘ └────────────┘
│ │
│ ▼
│ ┌─────────────────┐
│ │ Apache Kafka │
│ │ (Event Streams) │
│ └─────────────────┘
│ │
▼ ▼
┌──────────────┐ ┌───────────────┐
│ Keycloak │ │ PostgreSQL │
│ (Auth) │ │ Elasticsearch│
└──────────────┘ └───────────────┘
| Service | Responsibility | Technology |
|---|---|---|
| Identity Service | User authentication, authorization, profiles | Spring Boot + Keycloak |
| Product Catalog | Product management, categories, search | Spring Boot + Elasticsearch |
| Shopping Cart | Cart management, pricing calculations | Spring Boot + Redis |
| Order Management | Order lifecycle, saga orchestration | Spring Boot + PostgreSQL |
| Inventory | Stock tracking, reservations, alerts | Spring Boot + PostgreSQL |
| Payment | Payment processing, Stripe integration | Spring Boot + PostgreSQL |
| Shipping | Shipment creation, tracking | Spring Boot + PostgreSQL |
| Notification | Email/SMS notifications | Spring Boot + SendGrid |
| Accounting | Invoicing, revenue recognition | Spring Boot + PostgreSQL |
For detailed architecture, see: docs/ARCHITECTURE.md
User Journey:
- ✅ User registration and authentication
- ✅ Browse product catalog with search and filtering
- ✅ Add products to shopping cart
- ✅ Checkout and payment processing
- ✅ Order tracking and status updates
- ✅ Email notifications at key events
- ✅ Invoice generation and delivery
- Advanced inventory management with low-stock alerts
- Order modification and cancellation workflows
- Customer reviews and ratings
- Promotional codes and discounts
- Admin portal for catalog and order management
- Analytics dashboards
See: docs/ROADMAP.md for complete feature timeline
- Framework: Spring Boot 3.2, Spring Cloud
- Language: Java 17+
- Build Tool: Maven 3.8+
- API Gateway: Spring Cloud Gateway
- Service Discovery: Kubernetes DNS / Eureka
- Database: PostgreSQL (per-service databases)
- Cache: Redis
- Search: Elasticsearch
- Message Broker: Apache Kafka
- Framework: Vue.js 3 + TypeScript
- Build Tool: Vite
- State Management: Pinia
- Containerization: Docker
- Orchestration: Kubernetes
- Local Dev: Docker Compose
- CI/CD: GitHub Actions
- Logging: ELK Stack (Elasticsearch, Logstash, Kibana)
- Metrics: Prometheus + Grafana
- Tracing: Jaeger
- APM: Spring Boot Actuator + Micrometer
- Identity Provider: Keycloak (OAuth2/OIDC)
- Authentication: JWT tokens
- Authorization: Role-based access control (RBAC)
Ensure you have the following installed:
- Java 17+ (OpenJDK or Azul Zulu)
- Maven 3.8+ (Download)
- Docker 20+ and Docker Compose (Get Docker)
- Node.js 18+ (for frontend) (Download)
- Git (Download)
Note: The project is currently in the planning/restructuring phase. The following instructions will be functional after Week 1 of the roadmap.
# 1. Clone the repository
git clone https://github.com/deepkulk/SupplyBoost.git
cd SupplyBoost
# 2. Start infrastructure services (PostgreSQL, Kafka, Redis, etc.)
cd infrastructure/docker-compose
docker-compose up -d
# 3. Build all microservices
cd ../..
mvn clean install
# 4. Run services (once implemented)
# Individual services will have their own run instructions
# 5. Access the application
# Web UI: http://localhost:8080
# API Gateway: http://localhost:8080/api
# Grafana: http://localhost:3000
# Kibana: http://localhost:5601First-time setup: See CONTRIBUTING.md for detailed development environment setup.
SupplyBoost/
├── services/ # Microservices
│ ├── identity-service/ # User authentication & authorization
│ ├── product-catalog-service/ # Product management & search
│ ├── shopping-cart-service/ # Shopping cart management
│ ├── order-management-service/ # Order lifecycle & saga orchestration
│ ├── inventory-service/ # Stock tracking & reservations
│ ├── payment-service/ # Payment processing
│ ├── shipping-service/ # Shipment management
│ ├── notification-service/ # Email/SMS notifications
│ └── accounting-service/ # Invoicing & financial records
│
├── frontend/ # Frontend applications
│ └── web-app/ # Vue.js SPA
│
├── infrastructure/ # Infrastructure as Code
│ ├── docker-compose/ # Local development environment
│ └── kubernetes/ # K8s manifests (Helm charts)
│
├── docs/ # Documentation
│ ├── PRD.md # Product Requirements Document
│ ├── ARCHITECTURE.md # Technical architecture
│ ├── ROADMAP.md # Development roadmap
│ ├── adr/ # Architecture Decision Records
│ ├── assets/ # Images, diagrams
│ └── archive/ # Historical documents
│
├── scripts/ # Utility scripts
│ ├── setup-dev-env.sh # Development environment setup
│ ├── run-all-tests.sh # Run all tests
│ └── deploy.sh # Deployment automation
│
├── pom.xml # Maven parent POM
├── README.md # This file
├── CONTRIBUTING.md # Contribution guidelines
└── LICENSE # Apache 2.0 license
The project follows a 12-week development plan divided into three phases:
- ✅ Repository restructuring
- ✅ Comprehensive planning documents
- ✅ CI/CD pipeline setup
- ✅ Core services scaffolding (Identity, Product Catalog, Inventory)
- ✅ Shopping cart and order creation
- ✅ Payment and shipping services
- ✅ Event-driven saga implementation
- ✅ All 9 microservices operational
- ✅ Observability stack (ELK, Prometheus, Grafana, Jaeger)
- ✅ Security hardening (OWASP checks, Trivy scans, security headers)
- ✅ Performance testing with Gatling
- ✅ Kubernetes deployment manifests with HPA and Ingress
- ✅ Operational documentation and runbooks
Detailed roadmap: docs/ROADMAP.md
Progress Tracking: See GitHub Projects for current sprint status.
We welcome contributions! Whether you're fixing bugs, improving documentation, or proposing new features, your help is appreciated.
- Read CONTRIBUTING.md for detailed guidelines
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes with clear messages
- Push to your branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project adheres to the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code.
# Run tests before committing
mvn test
# Format code (Spotless)
mvn spotless:apply
# Check code coverage
mvn verify
open target/site/jacoco/index.html| Document | Description |
|---|---|
| PRD.md | Product Requirements Document - what we're building |
| ARCHITECTURE.md | System architecture and design patterns |
| ROADMAP.md | 12-week development plan |
| RESTRUCTURING_PLAN.md | Repository cleanup strategy |
Important architectural decisions are documented in docs/adr/:
- ADR-001: Microservices Architecture
- ADR-002: Event-Driven Communication (planned)
- ADR-003: Database-per-Service (planned)
- ADR-005: Monorepo Structure
Once services are implemented, API documentation will be available at:
- Swagger UI:
http://localhost:8080/swagger-ui - OpenAPI Spec:
http://localhost:8080/api-docs
Q: Is this production-ready? A: Not yet. This is an educational project. While we follow production best practices, it's designed for learning, not commercial deployment.
Q: Can I use this for my startup/company? A: Yes, under the Apache 2.0 license. However, you'll need significant additional work for true production readiness (security audit, scaling, compliance, etc.).
Q: Why not just use a monolith? A: Monoliths are often the right choice! This project explicitly chooses microservices for educational value. See ADR-001 for the full reasoning.
Q: How can I contribute?
A: Check CONTRIBUTING.md and look for issues labeled good first issue or help wanted.
Q: What's the deployment strategy? A: Local development uses Docker Compose. Production deployment targets Kubernetes (GKE/EKS/AKS). See docs/ARCHITECTURE.md.
- Issues: GitHub Issues - Bug reports and feature requests
- Discussions: GitHub Discussions - Questions and ideas
- Twitter: @saeid_amini - Project updates
- Inspired by eShopOnContainers (Microsoft)
- Architecture patterns from Building Microservices by Sam Newman
- DDD concepts from Domain-Driven Design by Eric Evans
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
Copyright © 2025 SupplyBoost Contributors
If you find this project helpful, please consider giving it a ⭐! It helps others discover the project.
Built with ❤️ for the developer community