# 25020073-zunn/bigproject architecture

> Architecture diagram of the GitHub repository 25020073-zunn/bigproject, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/25020073-zunn/bigproject
- Repository: https://github.com/25020073-zunn/bigproject

## Overview

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: [`src/main/java/com/auction/controller`](https://github.com/25020073-zunn/bigproject/tree/main/src/main/java/com/auction/controller) (Controllers), [`src/main/java/com/auction/service/AuctionService.java`](https://github.com/25020073-zunn/bigproject/blob/main/src/main/java/com/auction/service/AuctionService.java) (Auction service), [`src/main/java/com/auction/network/server/Server.java`](https://github.com/25020073-zunn/bigproject/blob/main/src/main/java/com/auction/network/server/Server.java) (TCP server), [`src/main/java/com/auction/network/client`](https://github.com/25020073-zunn/bigproject/tree/main/src/main/java/com/auction/network/client) (Network client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["JavaFX client"]
  node_main(("Main<br/>bootstrap<br/>[Main.java]"))
  node_fxml["FXML screens<br/>ui views"]
  node_controllers["Controllers"]
  node_uiutil["UI helpers<br/>ui support"]
  node_networkclient["Network client<br/>tcp client"]
end

subgraph group_core["Domain core"]
  node_messages["Message<br/>protocol<br/>[Message.java]"]
  node_auth["Auth service<br/>[AuthService.java]"]
  node_auctionsvc["Auction service"]
  node_usersvc["User service<br/>[UserService.java]"]
  node_imagesvc["Image service"]
  node_autobid{{"Auto bid<br/>strategy"}}
  node_itemfactory{{"Item factory<br/>[ItemFactory.java]"}}
  node_domain[("Auction model<br/>domain")]
  node_items[("Item types<br/>domain")]
  node_users[("User roles<br/>domain")]
  node_observer(("Auction observer<br/>realtime"))
end

subgraph group_server["Server & data"]
  node_serverapp(("TCP server<br/>[Server.java]"))
  node_daos["DAOs<br/>data access"]
  node_dbconn["DB connection<br/>mysql connector<br/>[DBConnection.java]"]
  node_schema["Schema init<br/>sql schema<br/>[01_schema.sql]"]
end

subgraph group_storage["Assets & deployment"]
  node_imageloader["Image loader<br/>asset path"]
  node_uploads[("Local images<br/>file storage")]
end

node_main -->|"loads"| node_fxml
node_main -->|"wires"| node_controllers
node_controllers -->|"uses"| node_uiutil
node_controllers -->|"calls"| node_auth
node_controllers -->|"calls"| node_auctionsvc
node_controllers -->|"calls"| node_usersvc
node_controllers -->|"uses"| node_imagesvc
node_auctionsvc -->|"creates"| node_itemfactory
node_auctionsvc -->|"applies"| node_autobid
node_auctionsvc -->|"manages"| node_domain
node_usersvc -->|"manages"| node_users
node_auth -->|"authenticates"| node_users
node_itemfactory -->|"instantiates"| node_items
node_auctionsvc -.->|"publishes"| node_observer
node_networkclient -->|"exchanges"| node_messages
node_networkclient -->|"connects"| node_serverapp
node_serverapp -.->|"notifies"| node_observer
node_serverapp -->|"uses"| node_daos
node_daos -->|"connects"| node_dbconn
node_dbconn -.->|"initializes"| node_schema
node_imagesvc -->|"resolves"| node_imageloader
node_imageloader -.->|"falls back to"| node_uploads
node_controllers -->|"requests"| node_networkclient
node_serverapp -->|"persists via"| node_dbconn

click node_main "https://github.com/25020073-zunn/bigproject/blob/main/src/main/java/com/auction/Main.java"
click node_fxml "https://github.com/25020073-zunn/bigproject/tree/main/src/main/resources/fxml"
click node_controllers "https://github.com/25020073-zunn/bigproject/tree/main/src/main/java/com/auction/controller"
click node_uiutil "https://github.com/25020073-zunn/bigproject/tree/main/src/main/java/com/auction/util"
click node_networkclient "https://github.com/25020073-zunn/bigproject/tree/main/src/main/java/com/auction/network/client"
click node_messages "https://github.com/25020073-zunn/bigproject/blob/main/src/main/java/com/auction/network/Message.java"
click node_auth "https://github.com/25020073-zunn/bigproject/blob/main/src/main/java/com/auction/service/AuthService.java"
click node_auctionsvc "https://github.com/25020073-zunn/bigproject/blob/main/src/main/java/com/auction/service/AuctionService.java"
click node_usersvc "https://github.com/25020073-zunn/bigproject/blob/main/src/main/java/com/auction/service/UserService.java"
click node_imagesvc "https://github.com/25020073-zunn/bigproject/blob/main/src/main/java/com/auction/service/ImageStorageService.java"
click node_autobid "https://github.com/25020073-zunn/bigproject/blob/main/src/main/java/com/auction/service/AutoBidStrategy.java"
click node_itemfactory "https://github.com/25020073-zunn/bigproject/blob/main/src/main/java/com/auction/factory/ItemFactory.java"
click node_domain "https://github.com/25020073-zunn/bigproject/tree/main/src/main/java/com/auction/model"
click node_items "https://github.com/25020073-zunn/bigproject/tree/main/src/main/java/com/auction/model/item"
click node_users "https://github.com/25020073-zunn/bigproject/tree/main/src/main/java/com/auction/model/user"
click node_observer "https://github.com/25020073-zunn/bigproject/tree/main/src/main/java/com/auction/observer"
click node_serverapp "https://github.com/25020073-zunn/bigproject/blob/main/src/main/java/com/auction/network/server/Server.java"
click node_daos "https://github.com/25020073-zunn/bigproject/tree/main/src/main/java/com/auction/dao"
click node_dbconn "https://github.com/25020073-zunn/bigproject/blob/main/src/main/java/com/auction/config/DBConnection.java"
click node_schema "https://github.com/25020073-zunn/bigproject/blob/main/src/main/resources/Database/init/01_schema.sql"
click node_imageloader "https://github.com/25020073-zunn/bigproject/blob/main/src/main/java/com/auction/util/AuctionImageLoader.java"
click node_uploads "https://github.com/25020073-zunn/bigproject/tree/main/uploads/images"

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_main,node_fxml,node_controllers,node_uiutil,node_networkclient toneBlue
class node_messages,node_auth,node_auctionsvc,node_usersvc,node_imagesvc,node_autobid,node_itemfactory,node_domain,node_items,node_users,node_observer toneAmber
class node_serverapp,node_daos,node_dbconn,node_schema toneMint
class node_imageloader,node_uploads toneRose
```

## Components

### JavaFX client

Desktop UI, navigation, and client-side networking.

- [Main](https://github.com/25020073-zunn/bigproject/blob/main/src/main/java/com/auction/Main.java): bootstrap · JavaFX application entry point. · `src/main/java/com/auction/Main.java`
- [FXML screens](https://github.com/25020073-zunn/bigproject/tree/main/src/main/resources/fxml): ui views · FXML-driven desktop screens for login, auctions, profile, admin, and history. · `src/main/resources/fxml`
- [Controllers](https://github.com/25020073-zunn/bigproject/tree/main/src/main/java/com/auction/controller): ui controllers · Screen controllers for login, auctions, creation, summary, profile, and admin flows. · `src/main/java/com/auction/controller`
- [UI helpers](https://github.com/25020073-zunn/bigproject/tree/main/src/main/java/com/auction/util): ui support · Scene switching, auth gating, alerts, session state, and async FX utilities. · `src/main/java/com/auction/util`
- [Network client](https://github.com/25020073-zunn/bigproject/tree/main/src/main/java/com/auction/network/client): tcp 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](https://github.com/25020073-zunn/bigproject/blob/main/src/main/java/com/auction/network/Message.java): protocol · Transport-level message abstraction used by client-server communication. · `src/main/java/com/auction/network/Message.java`
- [Auth service](https://github.com/25020073-zunn/bigproject/blob/main/src/main/java/com/auction/service/AuthService.java): service · Sign-in, sign-up, and credential handling. · `src/main/java/com/auction/service/AuthService.java`
- [Auction service](https://github.com/25020073-zunn/bigproject/blob/main/src/main/java/com/auction/service/AuctionService.java): service · Auction creation, bidding, summaries, and history orchestration. · `src/main/java/com/auction/service/AuctionService.java`
- [User service](https://github.com/25020073-zunn/bigproject/blob/main/src/main/java/com/auction/service/UserService.java): service · User profile and user-related operations. · `src/main/java/com/auction/service/UserService.java`
- [Image service](https://github.com/25020073-zunn/bigproject/blob/main/src/main/java/com/auction/service/ImageStorageService.java): service · Abstracts image persistence and retrieval. · `src/main/java/com/auction/service/ImageStorageService.java`
- [Auto bid](https://github.com/25020073-zunn/bigproject/blob/main/src/main/java/com/auction/service/AutoBidStrategy.java): strategy · Encapsulates automated bidding behavior. · `src/main/java/com/auction/service/AutoBidStrategy.java`
- [Item factory](https://github.com/25020073-zunn/bigproject/blob/main/src/main/java/com/auction/factory/ItemFactory.java): factory · Creates concrete item subtypes from category choice. · `src/main/java/com/auction/factory/ItemFactory.java`
- [Auction model](https://github.com/25020073-zunn/bigproject/tree/main/src/main/java/com/auction/model): domain · Auction, bid transaction, and shared entity records. · `src/main/java/com/auction/model`
- [Item types](https://github.com/25020073-zunn/bigproject/tree/main/src/main/java/com/auction/model/item): domain · Item hierarchy and lifecycle state for auction listings. · `src/main/java/com/auction/model/item`
- [User roles](https://github.com/25020073-zunn/bigproject/tree/main/src/main/java/com/auction/model/user): domain · User hierarchy and role-specific behavior for sellers, bidders, admins, and registered users. · `src/main/java/com/auction/model/user`
- [Auction observer](https://github.com/25020073-zunn/bigproject/tree/main/src/main/java/com/auction/observer): realtime · 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](https://github.com/25020073-zunn/bigproject/blob/main/src/main/java/com/auction/network/server/Server.java): server · Auction server entry point handling live auction operations and updates. · `src/main/java/com/auction/network/server/Server.java`
- [DAOs](https://github.com/25020073-zunn/bigproject/tree/main/src/main/java/com/auction/dao): data access · Auction and user data access layer. · `src/main/java/com/auction/dao`
- [DB connection](https://github.com/25020073-zunn/bigproject/blob/main/src/main/java/com/auction/config/DBConnection.java): mysql connector · Centralized database connectivity. · `src/main/java/com/auction/config/DBConnection.java`
- [Schema init](https://github.com/25020073-zunn/bigproject/blob/main/src/main/resources/Database/init/01_schema.sql): sql schema · Database schema initialization script. · `src/main/resources/Database/init/01_schema.sql`

### Assets & deployment

Image storage paths and containerized runtime support.

- [Image loader](https://github.com/25020073-zunn/bigproject/blob/main/src/main/java/com/auction/util/AuctionImageLoader.java): asset path · Resolves auction images from local or remote storage. · `src/main/java/com/auction/util/AuctionImageLoader.java`
- [Local images](https://github.com/25020073-zunn/bigproject/tree/main/uploads/images): file storage · Local image volume used when remote image storage is unavailable. · `uploads/images`

## Connections

- 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.