{"id":48586325,"url":"https://github.com/vivekanand-vr/wheelshift-backend","last_synced_at":"2026-04-08T18:10:04.786Z","repository":{"id":344989297,"uuid":"1144957550","full_name":"vivekanand-vr/wheelshift-backend","owner":"vivekanand-vr","description":"An enterprise-grade used car trading management system streamlining end-to-end vehicle lifecycle op- erations from acquisition to sales completion with real-time dashboards and analytics","archived":false,"fork":false,"pushed_at":"2026-03-26T17:26:51.000Z","size":922,"stargazers_count":0,"open_issues_count":5,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-03-27T03:39:32.035Z","etag":null,"topics":["docker-compose","mysql","spring-boot"],"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/vivekanand-vr.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-01-29T08:46:18.000Z","updated_at":"2026-03-17T05:21:18.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/vivekanand-vr/wheelshift-backend","commit_stats":null,"previous_names":["vivekanand-vr/wheelshift-backend"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/vivekanand-vr/wheelshift-backend","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vivekanand-vr%2Fwheelshift-backend","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vivekanand-vr%2Fwheelshift-backend/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vivekanand-vr%2Fwheelshift-backend/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vivekanand-vr%2Fwheelshift-backend/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vivekanand-vr","download_url":"https://codeload.github.com/vivekanand-vr/wheelshift-backend/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vivekanand-vr%2Fwheelshift-backend/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31567523,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-08T14:31:17.711Z","status":"ssl_error","status_checked_at":"2026-04-08T14:31:17.202Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5: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":["docker-compose","mysql","spring-boot"],"created_at":"2026-04-08T18:10:03.769Z","updated_at":"2026-04-08T18:10:04.721Z","avatar_url":"https://github.com/vivekanand-vr.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# WheelShift Pro — Backend\n\n\u003e Production-ready Spring Boot backend for a used-vehicle trading enterprise.\n\u003e Covers the full lifecycle of a sale: inventory, inspections, reservations, clients,\n\u003e employees, financials, tasks, events, and a multi-channel notification system —\n\u003e all secured by a fine-grained RBAC layer.\n\n---\n\n## Quick Start\n\n### Option 1 — Full Docker (Recommended)\n\n```bash\ngit clone \u003crepository-url\u003e\ncd wheelshift-backend\n\n# Start MySQL, Redis, Kafka, Kafka UI, phpMyAdmin, Redis Commander\ndocker-compose -f docker-compose-dev.yml up -d\n\n# Follow application logs\ndocker-compose -f docker-compose-dev.yml logs -f ws-pro\n\n# Tear down (keeps data)\ndocker-compose -f docker-compose-dev.yml down\n\n# Tear down + wipe all data\ndocker-compose -f docker-compose-dev.yml down -v\n```\n\n**Dev services:**\n\n| Service | URL |\n|---------|-----|\n| API | http://localhost:8080 |\n| Swagger UI | http://localhost:8080/swagger-ui.html |\n| Actuator / Health | http://localhost:8080/actuator/health |\n| phpMyAdmin | http://localhost:8081 |\n| Redis Commander | http://localhost:8082 |\n| Kafka UI | http://localhost:8083 |\n| Redis Insights | http://localhost:5540 |\n\n---\n\n### Option 2 — Local (IDE / Terminal)\n\n**Prerequisites:** Java 17, Maven 3.9+, Docker\n\n```bash\n# 1. Start infrastructure only\ndocker-compose -f docker-compose-dev.yml up -d mysql redis kafka\n\n# 2. Set environment variables\n#    IntelliJ: EnvFile plugin → add .env to Run Configuration\n#    Terminal:\nexport $(cat .env | grep -v '^#' | xargs)\n\n# 3. Run with dev profile\nmvn spring-boot:run -Dspring-boot.run.profiles=dev\n```\n\n---\n\n## Environment Variables\n\nAll secrets are injected via environment variables. The `.env` file at the project root\n(gitignored — never committed) holds local dev values:\n\n```bash\n# Database\nDB_URL=jdbc:mysql://localhost:3307/wheelshift_db?...\nDB_USERNAME=wheelshift_user\nDB_PASSWORD=your_password\n\n# Redis\nREDIS_HOST=localhost\nREDIS_PORT=6379\nREDIS_PASSWORD=\n\n# Kafka\n# localhost:9092 maps to the broker's EXTERNAL listener when running outside Docker\nKAFKA_BOOTSTRAP_SERVERS=localhost:9092\n\n# JWT  (generate with: openssl rand -hex 32)\nJWT_SECRET=change_this_in_production\nJWT_EXPIRATION_MS=86400000\n\n# AWS S3 (leave blank to use local file storage)\nAWS_ACCESS_KEY=\nAWS_SECRET_KEY=\n\n# AI Service (WheelShift AI — generates vehicle similarity recommendations)\n# Generate key with: python -c \"import secrets; print(secrets.token_hex(32))\"\nAI_SERVICE_BASE_URL=http://localhost:8000\nAI_SERVICE_API_KEY=change_this_in_production\nAI_SERVICE_ENABLED=true\n```\n\nNever hardcode secrets in `application.properties` or any committed file.\n\n---\n\n## Technology Stack\n\n| Category | Technology |\n|----------|------------|\n| Framework | Spring Boot 4.x |\n| Language | Java 17 |\n| Build | Maven 3.9+, JaCoCo, OWASP dependency-check |\n| Database | MySQL 8.0 |\n| ORM / Schema | Spring Data JPA (Hibernate) + Flyway |\n| Mapping | MapStruct 1.5.5 + Lombok |\n| Security | Spring Security 6, JWT (JJWT 0.12) |\n| Caching | Redis 7 (Spring Cache) |\n| Async Messaging | Apache Kafka 4.x, KRaft mode (spring-kafka) |\n| AI Integration | WheelShift AI Service (HTTP/WebClient, similarity recommendations + lead scoring) |\n| Real-time Push | Server-Sent Events (SSE) || Scheduling | `@Scheduled` + ShedLock (Redis distributed lock) |\n| Observability | Spring Actuator, Micrometer / Prometheus |\n| API Docs | SpringDoc OpenAPI 3 / Swagger UI |\n| Resilience | Resilience4j |\n| Testing | JUnit 5, Testcontainers, ArchUnit, REST Assured |\n| Logging | Logback (console + file; JSON via Logstash encoder in prod) |\n| Containers | Docker, Docker Compose |\n\n---\n\n## Features\n\n### Core Business\n- **Vehicle Inventory** — full car \u0026 motorcycle lifecycle (available → reserved → sold)\n- **Client Management** — profiles, purchase history, status tracking\n- **Employee Management** — staff profiles, roles, performance metrics\n- **Lead Management** — inquiry tracking and conversion pipeline\n- **Reservation System** — vehicle holds with deposit management; auto-expiry via scheduler\n- **Sales Processing** — transaction recording, commission tracking\n- **Financial Management** — transaction ledger and reporting\n- **Storage Locations** — multi-facility management with capacity tracking\n- **Inspections** — car and motorcycle inspection records\n- **Task Management** — task assignment, priorities, Kanban-style workflow\n- **Event Calendar** — appointments and event scheduling\n- **AI Recommendations** — similar vehicle suggestions powered by the WheelShift AI service (hybrid collaborative + content-based filtering); degrades gracefully when the AI service is unavailable\n- **AI Lead Scoring** — score inquiries by conversion likelihood (0–100) with Hot/Warm/Cold priority tiers and per-signal breakdowns; batch endpoint for dashboard enrichment (up to 50 inquiries per call); degrades gracefully when the AI service is unavailable\n\n### Role-Based Dashboards\nFive tailored dashboard views: Admin, Sales, Inspector, Finance, Store Manager.\n\n### Security \u0026 RBAC\n- 6 built-in roles: `SUPER_ADMIN`, `ADMIN`, `SALES`, `STORE_MANAGER`, `INSPECTOR`, `FINANCE`\n- 40+ fine-grained permissions in `resource:action` format\n- Data scoping (location / department-based filtering)\n- Resource-level ACLs for per-record access control\n- Stateless JWT authentication\n\n### Notifications\n- Multi-channel: In-App, Email, SMS, WhatsApp, Push, Webhook\n- Template engine with variable substitution\n- Per-employee channel preferences\n- **Delivery rules** — opt-out preferences, severity threshold filtering, quiet hours (auto-reschedule), digest batching (hourly scheduler)\n- **Async event-driven delivery via Apache Kafka** — producer publishes `NotificationJobMessage` to `notification.jobs.inapp` / `notification.jobs.email` topics; consumer processes with manual acknowledgement\n- **Real-time push via SSE** — consumers forward processed jobs to Redis Pub/Sub; a `MessageListener` picks them up and pushes to all active `SseEmitter` connections for the recipient\n- Stream endpoint: `GET /api/v1/notifications/stream/{recipientType}/{recipientId}` (`text/event-stream`)\n- Typed event catalogue via `NotificationEventType` enum (e.g. `INQUIRY_ASSIGNED`, `TASK_DUE`, `SALE_COMPLETED`)\n- Status tracking per delivery attempt\n\n---\n\n## API Reference\n\n**Base URL:** `http://localhost:8080/api/v1`\n**Interactive docs:** http://localhost:8080/swagger-ui.html\n\n| Group | Base Path | Controller |\n|-------|-----------|------------|\n| Auth | `/auth` | `AuthController` |\n| Cars | `/cars` | `CarController` |\n| Car Models | `/car-models` | `CarModelController` |\n| Car Inspections | `/car-inspections` | `CarInspectionController` |\n| Motorcycles | `/motorcycles` | `MotorcycleController` |\n| Motorcycle Models | `/motorcycle-models` | `MotorcycleModelController` |\n| Motorcycle Inspections | `/motorcycle-inspections` | `MotorcycleInspectionController` |\n| Clients | `/clients` | `ClientController` |\n| Employees | `/employees` | `EmployeeController` |\n| Sales | `/sales` | `SaleController` |\n| Reservations | `/reservations` | `ReservationController` |\n| Financial Transactions | `/financial-transactions` | `FinancialTransactionController` |\n| Storage Locations | `/storage-locations` | `StorageLocationController` |\n| Tasks | `/tasks` | `TaskController` |\n| Events | `/events` | `EventController` |\n| Inquiries | `/inquiries` | `InquiryController` |\n| Audit Logs | `/audit-logs` | `AuditLogController` |\n| Files | `/files` | `FileStorageController` |\n| Dashboards | `/dashboard` | `DashboardController` |\n| Notifications | `/notifications` | `NotificationController` |\n| Notification Preferences | `/notifications/preferences` | `NotificationPreferenceController` |\n| Notification Templates | `/notifications/templates` | `NotificationTemplateController` |\n| Roles | `/rbac/roles` | `RoleController` |\n| Permissions | `/rbac/permissions` | `PermissionController` |\n| Employee Roles | `/rbac/employees/{id}/roles` | `EmployeeRoleController` |\n| Employee Permissions | `/rbac/employee-permissions` | `EmployeePermissionController` |\n| Resource ACLs | `/rbac/acl` | `ResourceACLController` |\n| Data Scopes | `/rbac/employees/{id}/scope` | `DataScopeController` |\n| AI Recommendations | `/recommendations` | `RecommendationController` |\n| Lead Scoring | `/lead-scoring` | `LeadScoringController` |\n\n---\n\n## Database\n\nSchema is managed by **Flyway** — migrations run automatically on startup.\n\n| Version | Description |\n|---------|-------------|\n| V1 | Initial schema |\n| V2 | Seed data |\n| V3 | Column type fixes |\n| V4 | RBAC tables |\n| V5 | RBAC seed data |\n| V6 | Notifications tables |\n| V7 | Assign employee roles |\n| V8 | Fix roles + super admin |\n| V9 | Motorcycle tables |\n| V10 | Motorcycle movements |\n| V11 | Employee custom permissions |\n| V12 | File storage tables |\n| V13 | File storage columns |\n| V14 | Merge car-related tables |\n| V15 | Merge motorcycle-related tables |\n| V16 | Seed car models from dataset |\n| V17 | Seed motorcycle models from dataset |\n| V18 | Align notification event types to enum |\n| V19 | Storage location triggers |\n| V20 | Split vehicle count by type |\n| V21 | Add vehicle description |\n| V22 | Audit logs table |\n| V23 | Notification digest support (compound index) |\n\nMigration files: `src/main/resources/db/migration/`\nRollback scripts (manual): `src/main/resources/db/rollbacks/`\n\n**Never modify a committed migration.** Create a new `V{n+1}__...sql` for any schema change.\n\n### Running Migrations Manually\n\nMigrations run automatically on every app startup. The Flyway Maven plugin is pre-configured in `pom.xml` and reads `DB_USERNAME` / `DB_PASSWORD` from your environment, so you can run any Flyway goal with a single command:\n\n```bash\n# Source your credentials first (once per shell session)\nexport $(cat .env | grep -v '^#' | xargs)   # Linux/macOS\n# or load .env via your IDE's EnvFile plugin on Windows\n\n# Apply all pending migrations\nmvn flyway:migrate\n\n# Check current migration status\nmvn flyway:info\n\n# Validate applied migrations match the local scripts\nmvn flyway:validate\n\n# Repair the schema history table (use after fixing a failed migration)\nmvn flyway:repair\n```\n\nTo target a different host or database, override only what you need:\n\n```bash\nmvn flyway:migrate -Dflyway.url=jdbc:mysql://other-host:3306/wheelshift_db\n```\n\n\u003e Ensure the MySQL container is up (`docker-compose -f docker-compose-dev.yml up -d mysql`) before running any Flyway commands.\n\n---\n\n## Testing\n\n```bash\n# Full build: compile → test → coverage check → architecture rules\nmvn clean install\n\n# Tests only\nmvn test\n\n# Skip tests for fast iteration\nmvn install -DskipTests\n\n# Architecture rules only\nmvn test -Dtest=ArchitectureRulesTest\n\n# Coverage report → open target/site/jacoco/index.html after running\nmvn test jacoco:report\n```\n\n`ArchitectureRulesTest` enforces layered architecture rules on every build via ArchUnit.\nA failing architecture test is a **build failure** — fix the architecture, never skip the test.\n\n---\n\n## Development Status\n\n| Module | Status |\n|--------|--------|\n| Core Business APIs | ✅ Complete |\n| RBAC System | ✅ Complete |\n| Notification System | ✅ Complete |\n| Notification Delivery Rules | ✅ Complete |\n| Kafka Async Delivery | ✅ Complete |\n| SSE Real-time Push | ✅ Complete |\n| Dashboard System | ✅ Complete |\n| Redis Caching | ✅ Complete |\n| Task Management | ✅ Complete |\n| JWT Authentication | ✅ Complete |\n| Swagger / OpenAPI | ✅ Complete |\n| Error Handling | ✅ Complete |\n| Audit Logging | ✅ Complete |\n| File Storage (Local + S3) | ✅ Complete |\n| Database Migrations (V23) | ✅ Complete |\n| Docker Setup | ✅ Complete |\n| Observability (Actuator + Prometheus) | ✅ Complete |\n| Request Correlation (X-Request-Id) | ✅ Complete |\n| Distributed Scheduling (ShedLock) | ✅ Complete |\n| Architecture Tests (ArchUnit) | ✅ Complete |\n| AI Recommendations (Similarity API) | ✅ Complete |\n| AI Lead Scoring | ✅ Complete |\n| Unit Tests | 🔄 In Progress |\n| Integration Tests (Testcontainers) | 📋 Planned |\n| End-to-End Tests (REST Assured) | 📋 Planned |\n\n---\n\n## Documentation\n\n| Doc | Description |\n|-----|-------------|\n| [CONTRIBUTING.md](CONTRIBUTING.md) | Architecture diagrams, folder conventions, how to add features and migrations |\n| [docs/BUSINESS_LOGIC.md](docs/BUSINESS_LOGIC.md) | Complete business logic specification for all operations |\n| [docs/IMPLEMENTATION_STATUS.md](docs/IMPLEMENTATION_STATUS.md) | Implementation and test coverage status tracker |\n| [docs/DATABASE_DESIGN.md](docs/DATABASE_DESIGN.md) | Entity-relationship diagrams and database schema |\n| [docs/AI_SERVICE_OVERVIEW.md](docs/AI_SERVICE_OVERVIEW.md) | AI service architecture and implementation plan |\n| [docs/ARCHITECTURE_REVIEW.md](docs/ARCHITECTURE_REVIEW.md) | Architecture review, design patterns, improvement roadmap |\n| [docs/PRODUCT_DOCUMENTATION.md](docs/PRODUCT_DOCUMENTATION.md) | Full system and product overview |\n| [docs/DEVELOPMENT_GUIDE.md](docs/DEVELOPMENT_GUIDE.md) | Detailed development workflow |\n| [docs/rbac/RBAC_COMPLETE_GUIDE.md](docs/rbac/RBAC_COMPLETE_GUIDE.md) | RBAC system deep dive |\n| [docs/caching/REDIS_CACHING_GUIDE.md](docs/caching/REDIS_CACHING_GUIDE.md) | Redis caching implementation |\n| [docs/file-handling/README.md](docs/file-handling/README.md) | File storage and S3 migration |\n| [docs/features/notifications/README.md](docs/features/notifications/README.md) | Notification system |\n| [docs/features/dashboard/README.md](docs/features/dashboard/README.md) | Dashboard system |\n| [docs/features/tasks/README.md](docs/features/tasks/README.md) | Task management |\n| Swagger UI | http://localhost:8080/swagger-ui.html *(requires app running)* |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvivekanand-vr%2Fwheelshift-backend","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvivekanand-vr%2Fwheelshift-backend","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvivekanand-vr%2Fwheelshift-backend/lists"}