How 25020073-zunn/bigproject works
1. High-level shape
- This repository is a Java 17 auction system built as a client-server application.
- The UI client is a JavaFX desktop app driven by FXML screens.
- The server side is a separate TCP auction server.
- Persistence is backed by MySQL, and images are stored either in Cloudinary or a local image volume/server depending on configuration.
2. Runtime split: client vs server
- com.auction.network.client.* contains the client networking stack used by the JavaFX app to talk to the auction server.
- com.auction.network.server.Server is the TCP server entry point for auction operations and live updates.
- com.auction.Main is the client application bootstrap; the server is launched separately in the containerized setup.
3. UI layer
- The user interface is organized around FXML views in src/main/resources/fxml.
- Controllers in com.auction.controller map one-to-one with major screens such as login, register, auction list/detail, create auction, history, admin dashboard, profile, and asset detail.
- SceneNavigator, LoginStateHelper, and AlertHelper support view switching, auth-state gating, and user feedback across screens.
4. Application/service layer
- com.auction.service is the main business layer between controllers and lower-level infrastructure.
- AuthService handles sign-in / sign-up / credential logic.
- AuctionService orchestrates auction creation, bidding, summaries, and history.
- UserService manages user-related operations and profile data.
- AutoBidStrategy encapsulates automated bidding behavior.
- ImageStorageService abstracts image persistence away from the UI and auction logic.
5. Domain model
- Core entities live in com.auction.model.
- Auction, BidTransaction, and Entity represent the main auction records and transaction history.
- com.auction.model.item models item categories such as Art, Electronics, and Vehicle, with ItemStatus describing item lifecycle state.
- com.auction.model.user models user roles and capabilities: Admin, Seller, Bidder, RegisteredUser, and shared User.
- InsufficientFundsException indicates bidding logic enforces bidder balance constraints.
6. Persistence boundary
- com.auction.dao.AuctionDao and UserDao are the main data access layer.
- com.auction.config.DBConnection centralizes database connectivity.
- The schema is initialized from src/main/resources/Database/init/01_schema.sql.
- This layer is the boundary between domain/service logic and MySQL.
7. Network and messaging
- com.auction.network.Message is the transport-level message abstraction for client-server communication.
- ServerConnection, NetworkService, Client, and AuctionPayloadMapper handle message exchange and payload mapping on the client side.
- The network package is the path by which auction events, bids, and live updates move between the desktop client and the TCP server.
8. Realtime update model
- The repo includes an observer-style mechanism in com.auction.observer.
- AuctionSubject and AuctionObserver indicate auctions can push state changes to interested clients or listeners.
- This is important for diagramming because auction updates are not just request/response; some state changes are propagated asynchronously.
9. Auction workflow
- A typical flow is: user action in a JavaFX controller → service layer → DAO or network client → server/database.
- Auction listing and detail views are likely read-heavy screens, while create-auction and bidding screens trigger writes and server-side validation.
- AuctionSummaryController and AuctionHistoryController suggest reporting and audit-style views over completed and past transactions.
10. Image handling
- Images are handled as a separate concern from auction metadata.
- ImageStorageService plus AuctionImageLoader point to a dedicated storage/retrieval path for item photos.
- The README and config files show two backends: Cloudinary when credentials are present, otherwise local storage under uploads/images and/or a containerized image service on port 8081.
11. Factories and object creation
- ItemFactory encapsulates item subtype creation, so the model does not rely on controllers or services to know concrete item classes.
- This reduces coupling between item category selection in the UI and the actual domain object instantiation.
12. Utilities and cross-cutting concerns
- ValidationUtil likely centralizes form/input validation.
- PriceFormatter handles display formatting for currency or bid amounts.
- FxAsync suggests background work is marshaled back onto the JavaFX thread.
- UserSession stores the current authenticated user context across screens and service calls.
13. Deployment topology
- Docker Compose brings up the full stack: MySQL on 3307, TCP auction server on 5050, and a local image server on 8081.
- The JavaFX client runs on the host machine and connects to the containerized server.
- Persistent volumes are used for database data and uploaded images, so state survives restarts.
14. Testing and quality
- The repository has targeted tests for DAO, factory, model, network concurrency, auto-bidding, image storage, and image loading.
- That test split mirrors the architecture: persistence, domain behavior, networking, and utility/image subsystems are each independently validated.
15. What to show in an architecture diagram
- Draw four main zones: JavaFX client/UI, service/domain layer, TCP server + DAO/database, and image storage backend.
- Show controllers calling services, services using DAOs or network client, network client talking to the TCP server, and the server using MySQL plus broadcasting auction changes back to clients.
- Treat image upload as a side path to Cloudinary or local storage rather than part of the core bidding transaction flow.
Main entry points: controller Controllers · AuctionService.java Auction service · Server.java TCP server · client Network client
Components 22
JavaFX client
Desktop UI, navigation, and client-side networking.
- Main · JavaFX application entry point.
src/main/java/com/auction/Main.java - FXML screens · FXML-driven desktop screens for login, auctions, profile, admin, and history.
src/main/resources/fxml - Controllers · Screen controllers for login, auctions, creation, summary, profile, and admin flows.
src/main/java/com/auction/controller - UI helpers · Scene switching, auth gating, alerts, session state, and async FX utilities.
src/main/java/com/auction/util - Network client · Client-side message exchange, payload mapping, and server connection management.
src/main/java/com/auction/network/client
Domain core
Services, models, factories, and shared client-side logic.
- Message · Transport-level message abstraction used by client-server communication.
src/main/java/com/auction/network/Message.java - Auth service · Sign-in, sign-up, and credential handling.
src/main/java/com/auction/service/AuthService.java - Auction service · Auction creation, bidding, summaries, and history orchestration.
src/main/java/com/auction/service/AuctionService.java - User service · User profile and user-related operations.
src/main/java/com/auction/service/UserService.java - Image service · Abstracts image persistence and retrieval.
src/main/java/com/auction/service/ImageStorageService.java - Auto bid · Encapsulates automated bidding behavior.
src/main/java/com/auction/service/AutoBidStrategy.java - Item factory · Creates concrete item subtypes from category choice.
src/main/java/com/auction/factory/ItemFactory.java - Auction model · Auction, bid transaction, and shared entity records.
src/main/java/com/auction/model - Item types · Item hierarchy and lifecycle state for auction listings.
src/main/java/com/auction/model/item - User roles · User hierarchy and role-specific behavior for sellers, bidders, admins, and registered users.
src/main/java/com/auction/model/user - Auction observer · Observer-style update path for auction state changes.
src/main/java/com/auction/observer
Server & data
TCP server plus persistence boundary to MySQL.
- TCP server · Auction server entry point handling live auction operations and updates.
src/main/java/com/auction/network/server/Server.java - DAOs · Auction and user data access layer.
src/main/java/com/auction/dao - DB connection · Centralized database connectivity.
src/main/java/com/auction/config/DBConnection.java - Schema init · Database schema initialization script.
src/main/resources/Database/init/01_schema.sql
Assets & deployment
Image storage paths and containerized runtime support.
- Image loader · Resolves auction images from local or remote storage.
src/main/java/com/auction/util/AuctionImageLoader.java - Local images · Local image volume used when remote image storage is unavailable.
uploads/images
Connections 24
- Main → FXML screens: loads · Bootstraps the desktop UI from FXML screens.
- Main → Controllers: wires · Starts controller-driven application flow.
- Controllers → UI helpers: uses · Shares navigation, alerts, auth state, and FX threading helpers.
- Controllers → Auth service: calls · Login and registration screens invoke authentication logic.
- Controllers → Auction service: calls · Auction screens delegate listing, bidding, and summaries.
- Controllers → User service: calls · Profile and user-facing screens query user operations.
- Controllers → Image service: uses · Create/detail screens work with image persistence.
- Auction service → Item factory: creates · Selects concrete item subtype for listings.
- Auction service → Auto bid: applies · Uses automated bidding rules when needed.
- Auction service → Auction model: manages · Coordinates auction records and bid transactions.
- User service → User roles: manages · Operates on user accounts and roles.
- Auth service → User roles: authenticates · Validates credentials against user records.
- Item factory → Item types: instantiates · Builds concrete item subtypes.
- Auction service → Auction observer: publishes · Pushes auction state changes to listeners.
- Network client → Message: exchanges · Sends and receives transport messages.
- Network client → TCP server: connects · Client talks to the TCP auction server.
- TCP server → Auction observer: notifies · Broadcasts live auction updates.
- TCP server → DAOs: uses · Reads and writes auction and user data.
- DAOs → DB connection: connects · Obtains MySQL connections.
- DB connection → Schema init: initializes · Database schema is created from SQL init scripts.
- Image service → Image loader: resolves · Loads images from the active backend.
- Image loader → Local images: falls back to · Uses local image storage when remote storage is unavailable.
- Controllers → Network client: requests · UI actions trigger client-server operations for live auction data.
- TCP server → DB connection: persists via · Server-side operations ultimately depend on the database connection.