How phamdung005/distributed-auction-system works
1. This repository is a microservices-based online auction platform with a separate React frontend and multiple Node.js/Express backend services. The core architectural goal is realtime bidding with concurrency control, plus clean service boundaries via “database per service.”
2. The frontend is a Vite + React single-page app under frontend/. It is organized by user role and domain: auth, bidder, seller, admin, orders, support, and shared auction components. AuthContext, PrivateRoute, and the role-specific navbar variants indicate that routing and navigation are driven by authenticated user state and permissions.
3. The frontend talks to backend services through thin service clients in frontend/src/services/. These include REST APIs for admin, orders, wallet, notifications, and general API access, plus socket clients for realtime notification/order flows. That separation suggests UI components do not call backend endpoints directly; they go through a domain service layer.
4. services/auth-service owns registration, login, JWT issuance, and user identity synchronization. It contains its own User model, auth repository/service/controller stack, and JWT utilities. This service is the authentication boundary for the rest of the system, with other services relying on its auth middleware and token claims.
5. services/auction-service owns auction lifecycle data: auctions and auction registrations. It exposes controllers/routes for auction management and registration, with repository and service layers around MongoDB models. This service appears to handle seller-facing auction creation and bidder enrollment/participation rules.
6. services/bidding-service is the realtime core. It stores bids in its own database and includes Socket.io socket handling alongside standard REST endpoints. The presence of socketAuth and a dedicated socket handler indicates bid submission and bid event broadcasting are both authenticated and realtime.
7. The repository README explicitly calls out Redis locks for race-condition control during simultaneous bids. That means bidding is not just event-driven; it also depends on Redis as a concurrency primitive to serialize critical sections and prevent inconsistent winning bids when multiple users submit at once.
8. services/payment-service manages wallets, transactions, escrow, and user/payment-related state. It includes controllers for transaction, wallet, and user operations, plus a MoMo helper, so payment processing likely bridges internal wallet/escrow logic with an external payment gateway. This service also has event subscribers, which implies it reacts to domain events rather than being called only synchronously.
9. services/order-service owns post-auction fulfillment data. It stores orders and exposes order controllers/routes, with an event subscriber module showing it consumes events from other services to create or update order state. This is the handoff point from auction/winning-bid outcomes into delivery/order management.
10. services/notification-service is a realtime and scheduled messaging subsystem. It has a notification store, pub/sub service, scheduler, and socket support, which suggests three notification paths: persistent in-app notifications, broadcast/subscribe style delivery, and scheduled reminders or triggers. It is a cross-cutting service that listens to events from bidding, orders, payments, or auctions.
11. services/community-service is a separate social layer for posts and comments. It is isolated from the commerce flow and has its own models, repositories, controllers, and auth middleware. In an architecture diagram, it should be shown as an auxiliary domain service rather than part of the auction transaction pipeline.
12. Shared infrastructure lives in shared/database/ with common MongoDB and Redis connection code. This supports the service-per-database model while keeping connection setup consistent. Redis is particularly important as both a cache/concurrency tool and a pub/sub or socket-adjacent dependency.
13. Deployment is designed around containers and Kubernetes. Each service has a Dockerfile, there is a top-level docker-compose.yml for local development, and k8s/services/*.yaml defines individual service deployments. Infrastructure manifests include MongoDB variants, Redis, NGINX ingress, and Prometheus monitoring, showing the system is intended to scale horizontally and be observed in cluster.
14. The runtime data flow is roughly: frontend authenticates through auth-service, then consumes auction, bidding, payment/wallet, order, notification, and community APIs based on role. Realtime bid and notification updates travel through Socket.io-backed channels, while critical domain changes are persisted in each service’s own MongoDB database and coordinated across services via events, Redis, and JWT-protected service boundaries.
Main entry points: auth-service.yaml K8s deploy · services API clients · index.js Bidding service · mongodb.js MongoDB
Components 16
Frontend
React SPA and UI composition
- Auction UI · Role-based single-page frontend with auth-gated routes and domain pages
frontend/src/App.jsx - Auth state · Authentication state, route protection, and permission-aware navigation
frontend/src/contexts/AuthContext.jsx - API clients · Thin REST and socket clients for admin, orders, wallet, notifications, and realtime flows
frontend/src/services
Backend services
Domain services with isolated databases
- Auth service · Registration, login, JWT issuance, and user identity synchronization
services/auth-service/src/index.js - Auction service · Auction lifecycle and registration management
services/auction-service/src/index.js - Bidding service · Bid submission, socket broadcasting, and bid-state coordination
services/bidding-service/src/index.js - Payment service · Wallets, transactions, escrow, and payment integration
services/payment-service/src/index.js - Order service · Post-auction order state and event-driven order creation
services/order-service/src/index.js - Notification service · Persistent notifications, pub/sub delivery, scheduling, and sockets
services/notification-service/src/index.js - Community service · Posts and comments as an auxiliary community domain
services/community-service/src/index.js
Infrastructure
Shared persistence and deployment/runtime infrastructure
- MongoDB · Common MongoDB connection utilities supporting service-per-database deployments
shared/database/mongodb.js - Redis · Concurrency control, caching, and realtime/pubsub support
shared/database/redis.js - K8s deploy · Service deployments, ingress, monitoring, and MongoDB/Redis infrastructure manifests
k8s/services/auth-service.yaml - Local compose · Containerized local development entrypoint
docker-compose.yml - NGINX ingress · Ingress gateway and reverse-proxy configuration
nginx/nginx.conf - Monitoring · Cluster monitoring configuration
k8s/monitoring/prometheus.yaml
Connections 33
- Auction UI → Auth state: auth gates · Route protection and role-aware UI state
- Auction UI → API clients: uses · UI delegates backend access to service clients
- API clients → Auth service: login · Authentication and token-based identity flows
- API clients → Auction service: auction APIs · Auction browsing, creation, and registration
- API clients → Bidding service: bids · Realtime bid submission and updates
- API clients → Payment service: wallet/payments · Wallet, transaction, and payment actions
- API clients → Order service: orders · Order listing and detail views
- API clients → Notification service: notifications · Notification retrieval and realtime delivery
- API clients → Community service: community · Posts and comments domain access
- Auth service → MongoDB: stores users · Persistent auth identity data
- Auction service → MongoDB: stores auctions · Auction and registration persistence
- Bidding service → MongoDB: stores bids · Bid history and bid state persistence
- Payment service → MongoDB: stores wallet data · Transactions, users, and escrow records
- Order service → MongoDB: stores orders · Order persistence
- Notification service → MongoDB: stores notices · Notification persistence
- Community service → MongoDB: stores posts · Posts and comments persistence
- Bidding service → Redis: locks bids · Race-condition control for simultaneous bids
- Notification service → Redis: pubsub · Broadcast and realtime delivery support
- Auth service → Redis: sync/cache · Shared auth/session coordination support
- Bidding service → Notification service: events · Bid updates can trigger notifications
- Bidding service → Order service: winning bid · Auction outcome flows into fulfillment
- Payment service → Order service: payment events · Payment and escrow state can advance orders
- Auction service → Bidding service: auction state · Auction lifecycle constrains bidding participation
- K8s deploy → Auth service: deploys · Kubernetes service deployment
- K8s deploy → Auction service: deploys · Kubernetes service deployment
- K8s deploy → Bidding service: deploys · Kubernetes service deployment
- K8s deploy → Payment service: deploys · Kubernetes service deployment
- K8s deploy → Order service: deploys · Kubernetes service deployment
- K8s deploy → Notification service: deploys · Kubernetes service deployment
- K8s deploy → Community service: deploys · Kubernetes service deployment
- Local compose → K8s deploy: mirrors · Local container setup parallels cluster deployment
- NGINX ingress → K8s deploy: fronts · Ingress gateway for cluster traffic
- Monitoring → K8s deploy: observes · Monitoring for deployed services and infrastructure