# eauctionproject2025/eauction architecture

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

- Interactive diagram: https://gitdiagram.com/eauctionproject2025/eauction
- Repository: https://github.com/eauctionproject2025/eauction

## Overview

1. **Overall shape**
   - This repository is the **frontend for an e-auction platform**, built with **Next.js App Router** and React.
   - The app is not just static UI: it contains **server-side route handlers** under `src/app/api` and a full set of **page routes** for browsing auctions, managing accounts, and handling auth/payment flows.

2. **Main architectural boundary**
   - The frontend talks to a **separate backend service** over HTTP, as indicated by the README’s frontend/backend split and the env vars (`NEXT_PUBLIC_BACKEND_URL`, `NEXT_PUBLIC_FRONTEND_URL`).
   - In the repo, `src/app/api/authService.js` and the API route handlers act as the integration layer between UI pages and the external backend/auth system.

3. **Routing model**
   - The app uses **file-based routing** heavily:
     - public marketing/home surfaces: `src/app/page.js`, `allOffers`, `auctions`, `category`, `search`
     - authenticated surfaces: `dashboard/*`, `profile/[accountId]`, `createAuction`
     - auth flows: `src/app/(auth)/login`, `register`
     - payment callbacks: `payment/return`, `payment/success`
   - Dynamic routes such as `category/[id]`, `items/[id]`, and `profile/[accountId]` indicate the primary data entities are **categories, auction items, and user profiles**.

4. **Authentication and session management**
   - Authentication is centered on **NextAuth.js** via `src/app/api/auth/[...nextauth]/route.js`.
   - The README notes JWT/session enrichment with **user role** and **userId**, which supports role-aware navigation and access control across the app.
   - `src/components/SessionProviderWraper.jsx` suggests the session is propagated through the React tree for client components.

5. **Role-based application structure**
   - The app is organized around **buyer / seller / admin** roles:
     - `dashboard/buyer`
     - `dashboard/seller`
     - `dashboard/admin`
   - `src/hooks/useRole.jsx` and `src/components/navbar.jsx` imply that role is used to drive:
     - which links/actions appear
     - which dashboard view is shown
     - which operations are allowed, such as creating or deleting auctions.

6. **Auction domain flow**
   - The core business object is the **auction**, with pages and components for listing, viewing, creating, and bidding.
   - Key surfaces:
     - listing: `page.js`, `allOffers`, `auctions`, `category`, `search`
     - detail: `items/[id]`
     - creation: `createAuction/page.jsx`
     - seller history/profile: `profile/[accountId]`
   - The README describes auction data as including title, description, starting price, seller, bids, start/end time, and image; the UI components in `src/components` reinforce this model.

7. **Data flow for browsing**
   - Home and listing pages fetch auction/category data from the backend or API routes, then render reusable cards/lists.
   - Components like `AuctionList.jsx`, `auction.jsx`, `categoryCard.jsx`, `CarouselSlide.jsx`, and `Banner.jsx` show that the UI is assembled from **reusable display widgets** rather than monolithic pages.
   - Skeleton components such as `homeSkeleton.jsx`, `itemSkeleton.jsx`, and `profileSkeleton.jsx` indicate loading states are first-class in the UX.

8. **Data flow for bidding and auction detail**
   - `src/app/items/[id]/page.jsx` is the main auction-detail interaction point.
   - The README indicates it fetches a single auction, displays bids, validates and submits a bid, and computes remaining time.
   - `CountdownTimer.jsx` and `currencyFormat.jsx` support the auction-time and monetary display logic, which are important UI concerns for the bidding flow.

9. **Seller and admin management flows**
   - Sellers can create and manage auctions through `createAuction/page.jsx` and profile-related pages.
   - Admin and seller dashboards are split into dedicated pages under `dashboard/`, with `DashboardSidebar.jsx` likely providing the shared navigation shell.
   - `CategoryManager.jsx` and `UserList.jsx` suggest admin-style management views for catalog and user oversight.

10. **Payment and post-payment callbacks**
   - The `payment/return` and `payment/success` routes show the app integrates with an **external payment gateway** or redirect-based checkout flow.
   - `payment/success/SuccessClient.jsx` implies the final success screen has client-side behavior, likely to confirm or display transaction state after redirect.

11. **Layout, theming, and shared shell**
   - `src/app/layout.js` and `src/app/dashboard/layout.js` define the global and dashboard-specific shells.
   - Shared UI such as `navbar.jsx`, `footer.jsx`, `LayoutShell.jsx`, and `Alert.jsx` creates consistent chrome across routes.
   - `src/context/ThemeContext.js` indicates the app also has a cross-cutting theme state, separate from business data.

12. **Static assets and presentation layer**
   - Visual assets are organized under `public` and `src/public` by domain area: background, category, item, profile, icons, social icons.
   - This supports a presentation-heavy marketplace UI where imagery is part of the primary information model for auctions and profiles.

13. **Backend responsibilities implied by the frontend**
   - The README describes a backend with **Express, MongoDB, JWT auth, auction APIs, and role enforcement**.
   - From this repo’s perspective, those concerns are external services; the frontend’s architectural role is to:
     - authenticate users
     - fetch domain data
     - render role-specific experiences
     - submit auction/bid/payment actions
     - respond to redirects and session state.

14. **How to draw the architecture**
   - A good diagram should show:
     - browser/client UI at the center
     - Next.js route layer with public, auth, dashboard, auction, category, search, profile, and payment routes
     - NextAuth session/auth boundary
     - API route layer for auth/category integration
     - external backend service as the source of auction/user data and business rules
     - payment provider as an external redirect/callback participant
     - shared UI/components/context as cross-cutting support across pages.

Main entry points: [`src/app/layout.js`](https://github.com/eauctionproject2025/eauction/blob/main/src/app/layout.js) (App shell), [`src/app/api/auth/[...nextauth]/route.js`](https://github.com/eauctionproject2025/eauction/blob/main/src/app/api/auth/[...nextauth]/route.js) (NextAuth), [`src/app/items/[id]/page.jsx`](https://github.com/eauctionproject2025/eauction/blob/main/src/app/items/[id]/page.jsx) (Item detail), [`src/app/dashboard/layout.js`](https://github.com/eauctionproject2025/eauction/blob/main/src/app/dashboard/layout.js) (Dashboard shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client UI"]
  node_browser(("Browser<br/>client"))
end

subgraph group_routes["Next.js Routes"]
  node_app_shell["App shell<br/>layout<br/>[layout.js]"]
  node_home["Home<br/>route<br/>[page.js]"]
  node_public_catalog["Browse<br/>route group"]
  node_auth_pages["Auth pages<br/>route group"]
  node_auction_detail["Item detail<br/>route<br/>[page.jsx]"]
  node_create_auction["Create auction<br/>route<br/>[page.jsx]"]
  node_profile_page["Profile<br/>route<br/>[page.jsx]"]
  node_dashboard_shell["Dashboard shell<br/>layout<br/>[layout.js]"]
  node_role_dashboards["Role dashboards<br/>route group"]
  node_payment_flow["Payment flow<br/>route group"]
  node_nextauth[("NextAuth<br/>auth route<br/>[route.js]")]
  node_api_bridge["API bridge<br/>server adapter<br/>[authService.js]"]
  node_category_api["Category API<br/>route handler<br/>[route.js]"]
end

subgraph group_shared["Shared UI"]
  node_session_ui["Session UI<br/>provider"]
  node_role_hook["Role hook<br/>[useRole.jsx]"]
  node_shared_components["Shared components<br/>ui kit"]
  node_theme_ctx["Theme context<br/>[ThemeContext.js]"]
end

subgraph group_external["External Services"]
  node_backend[("Backend service<br/>external HTTP API")]
  node_payment_gateway[("Payment gateway<br/>external redirect service")]
end

node_browser -->|"loads"| node_app_shell
node_app_shell -->|"renders"| node_home
node_app_shell -->|"routes to"| node_public_catalog
node_app_shell -->|"routes to"| node_auth_pages
node_app_shell -->|"routes to"| node_auction_detail
node_app_shell -->|"routes to"| node_create_auction
node_app_shell -->|"routes to"| node_profile_page
node_app_shell -->|"routes to"| node_dashboard_shell
node_dashboard_shell -->|"hosts"| node_role_dashboards
node_app_shell -->|"routes to"| node_payment_flow
node_auth_pages -->|"authenticates via"| node_nextauth
node_session_ui -->|"consumes"| node_nextauth
node_role_hook -->|"reads role"| node_nextauth
node_shared_components -->|"builds UI"| node_public_catalog
node_shared_components -->|"builds UI"| node_auction_detail
node_shared_components -->|"builds UI"| node_dashboard_shell
node_theme_ctx -->|"cross-cuts"| node_app_shell
node_api_bridge -->|"calls"| node_backend
node_category_api -->|"calls"| node_backend
node_nextauth -.->|"verifies users"| node_backend
node_auction_detail -->|"fetches and bids"| node_backend
node_public_catalog -->|"fetches listings"| node_backend
node_profile_page -->|"fetches account data"| node_backend
node_create_auction -->|"creates auction"| node_backend
node_payment_flow -->|"redirects to"| node_payment_gateway
node_payment_gateway -.->|"returns to"| node_payment_flow

click node_app_shell "https://github.com/eauctionproject2025/eauction/blob/main/src/app/layout.js"
click node_home "https://github.com/eauctionproject2025/eauction/blob/main/src/app/page.js"
click node_auction_detail "https://github.com/eauctionproject2025/eauction/blob/main/src/app/items/[id]/page.jsx"
click node_create_auction "https://github.com/eauctionproject2025/eauction/blob/main/src/app/createAuction/page.jsx"
click node_profile_page "https://github.com/eauctionproject2025/eauction/blob/main/src/app/profile/[accountId]/page.jsx"
click node_dashboard_shell "https://github.com/eauctionproject2025/eauction/blob/main/src/app/dashboard/layout.js"
click node_nextauth "https://github.com/eauctionproject2025/eauction/blob/main/src/app/api/auth/[...nextauth]/route.js"
click node_api_bridge "https://github.com/eauctionproject2025/eauction/blob/main/src/app/api/authService.js"
click node_category_api "https://github.com/eauctionproject2025/eauction/blob/main/src/app/api/categories/route.js"
click node_session_ui "https://github.com/eauctionproject2025/eauction/blob/main/src/components/SessionProviderWraper.jsx"
click node_role_hook "https://github.com/eauctionproject2025/eauction/blob/main/src/hooks/useRole.jsx"
click node_theme_ctx "https://github.com/eauctionproject2025/eauction/blob/main/src/context/ThemeContext.js"

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_browser toneBlue
class node_app_shell,node_home,node_public_catalog,node_auth_pages,node_auction_detail,node_create_auction,node_profile_page,node_dashboard_shell,node_role_dashboards,node_payment_flow,node_nextauth,node_api_bridge,node_category_api toneAmber
class node_session_ui,node_role_hook,node_shared_components,node_theme_ctx toneMint
class node_backend,node_payment_gateway toneRose
```

## Components

### Client UI

Browser-facing app surfaces

- **Browser**: client · End-user entry point

### Next.js Routes

File-based pages and route handlers

- [App shell](https://github.com/eauctionproject2025/eauction/blob/main/src/app/layout.js): layout · Global Next.js layout and providers · `src/app/layout.js`
- [Home](https://github.com/eauctionproject2025/eauction/blob/main/src/app/page.js): route · Landing and featured marketplace entry · `src/app/page.js`
- **Browse**: route group · Public listing and category discovery pages
- **Auth pages**: route group · Login and registration flows
- [Item detail](https://github.com/eauctionproject2025/eauction/blob/main/src/app/items/[id]/page.jsx): route · Auction detail and bidding flow · `src/app/items/[id]/page.jsx`
- [Create auction](https://github.com/eauctionproject2025/eauction/blob/main/src/app/createAuction/page.jsx): route · Seller auction creation page · `src/app/createAuction/page.jsx`
- [Profile](https://github.com/eauctionproject2025/eauction/blob/main/src/app/profile/[accountId]/page.jsx): route · Account and seller history view · `src/app/profile/[accountId]/page.jsx`
- [Dashboard shell](https://github.com/eauctionproject2025/eauction/blob/main/src/app/dashboard/layout.js): layout · Role dashboard layout and navigation frame · `src/app/dashboard/layout.js`
- **Role dashboards**: route group · Buyer, seller, and admin dashboard pages
- **Payment flow**: route group · Redirect return and success handling
- [NextAuth](https://github.com/eauctionproject2025/eauction/blob/main/src/app/api/auth/[...nextauth]/route.js): auth route · Session and JWT authentication endpoint · `src/app/api/auth/[...nextauth]/route.js`
- [API bridge](https://github.com/eauctionproject2025/eauction/blob/main/src/app/api/authService.js): server adapter · Frontend integration helpers for backend calls · `src/app/api/authService.js`
- [Category API](https://github.com/eauctionproject2025/eauction/blob/main/src/app/api/categories/route.js): route handler · Categories integration endpoint · `src/app/api/categories/route.js`

### Shared UI

Reusable components, context, and hooks

- [Session UI](https://github.com/eauctionproject2025/eauction/blob/main/src/components/SessionProviderWraper.jsx): provider · Session propagation into client components · `src/components/SessionProviderWraper.jsx`
- [Role hook](https://github.com/eauctionproject2025/eauction/blob/main/src/hooks/useRole.jsx): hook · Role-aware UI gating and navigation · `src/hooks/useRole.jsx`
- **Shared components**: ui kit · Reusable cards, lists, nav, timers, and skeletons
- [Theme context](https://github.com/eauctionproject2025/eauction/blob/main/src/context/ThemeContext.js): context · Cross-cutting theme state · `src/context/ThemeContext.js`

### External Services

Systems this frontend integrates with

- **Backend service**: external HTTP API · Separate business-logic and data service
- **Payment gateway**: external redirect service · Checkout and callback provider

## Connections

- Browser → App shell: loads · Client starts in the app shell
- App shell → Home: renders · Global layout hosts the landing page
- App shell → Browse: routes to · Public marketplace browsing
- App shell → Auth pages: routes to · Auth entry points
- App shell → Item detail: routes to · Auction detail and bidding
- App shell → Create auction: routes to · Seller creation flow
- App shell → Profile: routes to · Account profile and history
- App shell → Dashboard shell: routes to · Authenticated dashboard area
- Dashboard shell → Role dashboards: hosts · Buyer, seller, and admin pages
- App shell → Payment flow: routes to · Payment return and success screens
- Auth pages → NextAuth: authenticates via · Login and registration rely on session auth
- Session UI → NextAuth: consumes · Session provider wraps NextAuth state
- Role hook → NextAuth: reads role · Role-aware UI depends on session claims
- Shared components → Browse: builds UI · Cards, banners, and lists power browsing pages
- Shared components → Item detail: builds UI · Timers, formatting, and auction display
- Shared components → Dashboard shell: builds UI · Sidebar and dashboard widgets
- Theme context → App shell: cross-cuts · Theme state available across the app
- API bridge → Backend service: calls · Frontend delegates data and action requests
- Category API → Backend service: calls · Category operations go through backend service
- NextAuth → Backend service: verifies users · Auth/session depends on external backend identity data
- Item detail → Backend service: fetches and bids · Auction detail reads data and submits bids
- Browse → Backend service: fetches listings · Marketplace browsing is backend-driven
- Profile → Backend service: fetches account data · Profile and seller history come from backend data
- Create auction → Backend service: creates auction · Seller submits new auction data
- Payment flow → Payment gateway: redirects to · External checkout and callback handling
- Payment gateway → Payment flow: returns to · Post-payment redirect lands back in app