# phamdung005/distributed-auction-system architecture

> Architecture diagram of the GitHub repository phamdung005/distributed-auction-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/phamdung005/distributed-auction-system
- Repository: https://github.com/phamdung005/distributed-auction-system

## Overview

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: [`k8s/services/auth-service.yaml`](https://github.com/phamdung005/distributed-auction-system/blob/master/k8s/services/auth-service.yaml) (K8s deploy), [`frontend/src/services`](https://github.com/phamdung005/distributed-auction-system/tree/master/frontend/src/services) (API clients), [`services/bidding-service/src/index.js`](https://github.com/phamdung005/distributed-auction-system/blob/master/services/bidding-service/src/index.js) (Bidding service), [`shared/database/mongodb.js`](https://github.com/phamdung005/distributed-auction-system/blob/master/shared/database/mongodb.js) (MongoDB)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["Auction UI<br/>Vite React SPA<br/>[App.jsx]"]
  node_frontend_auth(("Auth state<br/>React context<br/>[AuthContext.jsx]"))
  node_frontend_clients["API clients<br/>Service layer"]
end

subgraph group_services["Backend services"]
  node_auth_service["Auth service<br/>Node auth API<br/>[index.js]"]
  node_auction_service["Auction service<br/>Node auction API<br/>[index.js]"]
  node_bidding_service["Bidding service<br/>Realtime bidding<br/>[index.js]"]
  node_payment_service["Payment service<br/>Wallet and escrow<br/>[index.js]"]
  node_order_service["Order service<br/>Fulfillment API<br/>[index.js]"]
  node_notification_service["Notification service<br/>Realtime messaging<br/>[index.js]"]
  node_community_service["Community service<br/>Social API<br/>[index.js]"]
end

subgraph group_infra["Infrastructure"]
  node_mongodb_shared[("MongoDB<br/>Shared datastore<br/>[mongodb.js]")]
  node_redis_shared[("Redis<br/>Locking and pubsub<br/>[redis.js]")]
  node_k8s_deploy["K8s deploy<br/>Cluster manifests<br/>[auth-service.yaml]"]
  node_docker_compose["Local compose<br/>Dev orchestration<br/>[docker-compose.yml]"]
  node_nginx_ingress["NGINX ingress<br/>Edge proxy<br/>[nginx.conf]"]
  node_prometheus["Monitoring<br/>Metrics stack<br/>[prometheus.yaml]"]
end

node_frontend_app -->|"auth gates"| node_frontend_auth
node_frontend_app -->|"uses"| node_frontend_clients
node_frontend_clients -->|"login"| node_auth_service
node_frontend_clients -->|"auction APIs"| node_auction_service
node_frontend_clients -->|"bids"| node_bidding_service
node_frontend_clients -->|"wallet/payments"| node_payment_service
node_frontend_clients -->|"orders"| node_order_service
node_frontend_clients -->|"notifications"| node_notification_service
node_frontend_clients -->|"community"| node_community_service
node_auth_service -->|"stores users"| node_mongodb_shared
node_auction_service -->|"stores auctions"| node_mongodb_shared
node_bidding_service -->|"stores bids"| node_mongodb_shared
node_payment_service -->|"stores wallet data"| node_mongodb_shared
node_order_service -->|"stores orders"| node_mongodb_shared
node_notification_service -->|"stores notices"| node_mongodb_shared
node_community_service -->|"stores posts"| node_mongodb_shared
node_bidding_service -->|"locks bids"| node_redis_shared
node_notification_service -->|"pubsub"| node_redis_shared
node_auth_service -->|"sync/cache"| node_redis_shared
node_bidding_service -.->|"events"| node_notification_service
node_bidding_service -.->|"winning bid"| node_order_service
node_payment_service -.->|"payment events"| node_order_service
node_auction_service -.->|"auction state"| node_bidding_service
node_k8s_deploy -->|"deploys"| node_auth_service
node_k8s_deploy -->|"deploys"| node_auction_service
node_k8s_deploy -->|"deploys"| node_bidding_service
node_k8s_deploy -->|"deploys"| node_payment_service
node_k8s_deploy -->|"deploys"| node_order_service
node_k8s_deploy -->|"deploys"| node_notification_service
node_k8s_deploy -->|"deploys"| node_community_service
node_docker_compose -.->|"mirrors"| node_k8s_deploy
node_nginx_ingress -->|"fronts"| node_k8s_deploy
node_prometheus -.->|"observes"| node_k8s_deploy

click node_frontend_app "https://github.com/phamdung005/distributed-auction-system/blob/master/frontend/src/App.jsx"
click node_frontend_auth "https://github.com/phamdung005/distributed-auction-system/blob/master/frontend/src/contexts/AuthContext.jsx"
click node_frontend_clients "https://github.com/phamdung005/distributed-auction-system/tree/master/frontend/src/services"
click node_auth_service "https://github.com/phamdung005/distributed-auction-system/blob/master/services/auth-service/src/index.js"
click node_auction_service "https://github.com/phamdung005/distributed-auction-system/blob/master/services/auction-service/src/index.js"
click node_bidding_service "https://github.com/phamdung005/distributed-auction-system/blob/master/services/bidding-service/src/index.js"
click node_payment_service "https://github.com/phamdung005/distributed-auction-system/blob/master/services/payment-service/src/index.js"
click node_order_service "https://github.com/phamdung005/distributed-auction-system/blob/master/services/order-service/src/index.js"
click node_notification_service "https://github.com/phamdung005/distributed-auction-system/blob/master/services/notification-service/src/index.js"
click node_community_service "https://github.com/phamdung005/distributed-auction-system/blob/master/services/community-service/src/index.js"
click node_mongodb_shared "https://github.com/phamdung005/distributed-auction-system/blob/master/shared/database/mongodb.js"
click node_redis_shared "https://github.com/phamdung005/distributed-auction-system/blob/master/shared/database/redis.js"
click node_k8s_deploy "https://github.com/phamdung005/distributed-auction-system/blob/master/k8s/services/auth-service.yaml"
click node_docker_compose "https://github.com/phamdung005/distributed-auction-system/blob/master/docker-compose.yml"
click node_nginx_ingress "https://github.com/phamdung005/distributed-auction-system/blob/master/nginx/nginx.conf"
click node_prometheus "https://github.com/phamdung005/distributed-auction-system/blob/master/k8s/monitoring/prometheus.yaml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_frontend_app,node_frontend_auth,node_frontend_clients toneBlue
class node_auth_service,node_auction_service,node_bidding_service,node_payment_service,node_order_service,node_notification_service,node_community_service toneAmber
class node_mongodb_shared,node_redis_shared,node_k8s_deploy,node_docker_compose,node_nginx_ingress,node_prometheus toneMint
```

## Components

### Frontend

React SPA and UI composition

- [Auction UI](https://github.com/phamdung005/distributed-auction-system/blob/master/frontend/src/App.jsx): Vite React SPA · Role-based single-page frontend with auth-gated routes and domain pages · `frontend/src/App.jsx`
- [Auth state](https://github.com/phamdung005/distributed-auction-system/blob/master/frontend/src/contexts/AuthContext.jsx): React context · Authentication state, route protection, and permission-aware navigation · `frontend/src/contexts/AuthContext.jsx`
- [API clients](https://github.com/phamdung005/distributed-auction-system/tree/master/frontend/src/services): Service layer · 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](https://github.com/phamdung005/distributed-auction-system/blob/master/services/auth-service/src/index.js): Node auth API · Registration, login, JWT issuance, and user identity synchronization · `services/auth-service/src/index.js`
- [Auction service](https://github.com/phamdung005/distributed-auction-system/blob/master/services/auction-service/src/index.js): Node auction API · Auction lifecycle and registration management · `services/auction-service/src/index.js`
- [Bidding service](https://github.com/phamdung005/distributed-auction-system/blob/master/services/bidding-service/src/index.js): Realtime bidding · Bid submission, socket broadcasting, and bid-state coordination · `services/bidding-service/src/index.js`
- [Payment service](https://github.com/phamdung005/distributed-auction-system/blob/master/services/payment-service/src/index.js): Wallet and escrow · Wallets, transactions, escrow, and payment integration · `services/payment-service/src/index.js`
- [Order service](https://github.com/phamdung005/distributed-auction-system/blob/master/services/order-service/src/index.js): Fulfillment API · Post-auction order state and event-driven order creation · `services/order-service/src/index.js`
- [Notification service](https://github.com/phamdung005/distributed-auction-system/blob/master/services/notification-service/src/index.js): Realtime messaging · Persistent notifications, pub/sub delivery, scheduling, and sockets · `services/notification-service/src/index.js`
- [Community service](https://github.com/phamdung005/distributed-auction-system/blob/master/services/community-service/src/index.js): Social API · Posts and comments as an auxiliary community domain · `services/community-service/src/index.js`

### Infrastructure

Shared persistence and deployment/runtime infrastructure

- [MongoDB](https://github.com/phamdung005/distributed-auction-system/blob/master/shared/database/mongodb.js): Shared datastore · Common MongoDB connection utilities supporting service-per-database deployments · `shared/database/mongodb.js`
- [Redis](https://github.com/phamdung005/distributed-auction-system/blob/master/shared/database/redis.js): Locking and pubsub · Concurrency control, caching, and realtime/pubsub support · `shared/database/redis.js`
- [K8s deploy](https://github.com/phamdung005/distributed-auction-system/blob/master/k8s/services/auth-service.yaml): Cluster manifests · Service deployments, ingress, monitoring, and MongoDB/Redis infrastructure manifests · `k8s/services/auth-service.yaml`
- [Local compose](https://github.com/phamdung005/distributed-auction-system/blob/master/docker-compose.yml): Dev orchestration · Containerized local development entrypoint · `docker-compose.yml`
- [NGINX ingress](https://github.com/phamdung005/distributed-auction-system/blob/master/nginx/nginx.conf): Edge proxy · Ingress gateway and reverse-proxy configuration · `nginx/nginx.conf`
- [Monitoring](https://github.com/phamdung005/distributed-auction-system/blob/master/k8s/monitoring/prometheus.yaml): Metrics stack · Cluster monitoring configuration · `k8s/monitoring/prometheus.yaml`

## Connections

- 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
