# hackyourfutureprojects/c54-final-project-group-b architecture

> Architecture diagram of the GitHub repository hackyourfutureprojects/c54-final-project-group-b, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hackyourfutureprojects/c54-final-project-group-b
- Repository: https://github.com/hackyourfutureprojects/c54-final-project-group-b

## Overview

1. **Overall shape**
   - BiCycleL is a two-tier MERN application: a React/Vite client in `client/` and an Express/Node API in `server/`, with MongoDB/Mongoose as the system of record.
   - Real-time features are handled separately through Socket.IO, not through the REST API.

2. **Client boundary**
   - The frontend is organized by route-level pages (`client/src/pages`) and reusable components (`client/src/components`).
   - Data access is centralized through hooks and service wrappers (`client/src/hooks/useApi.js`, `client/src/services/api.js`, page-specific hooks like `useChat`, `useListingDetail`, `useInbox`), which keeps UI components mostly presentation-focused.

3. **Client state and app shell**
   - Cross-cutting state lives in React contexts: auth, theme, notifications, toasts, and socket connection (`client/src/contexts`).
   - Route protection is enforced on the client with wrappers like `ProtectedRoute`, `PublicOnlyRoute`, `AdminRoute`, and `RoleGate`, which define access boundaries for authenticated users, guests, and admins.

4. **Primary product domains on the client**
   - The main user journeys are: marketplace browsing and listing detail, listing creation/editing, favorites, inbox/chat, reviews, profile/account settings, and admin management.
   - Search/filter UX is a dedicated subsystem (`HeroFilter`, range sliders, city search, filter chips), while listings also have specialized UI for cards, carousels, maps, and form step flows.

5. **Real-time messaging and notifications**
   - The messaging layer is split between the `SocketProvider`/`useSocket` client infrastructure and chat/inbox pages.
   - This supports live chat, typing/online indicators, unread counts, and notification updates, so these features depend on persistent socket state in addition to REST fetches.

6. **Server application structure**
   - The backend is organized around Express routes, controllers, middleware, and Mongoose models under `server/src/`.
   - Routes are split by domain: users/auth, listings, favorites, messages, notifications, reports, reviews, and admin. Controllers contain the domain logic; models define persistence and relationships.

7. **Core backend domains**
   - `Listing`, `Favorite`, `Message`, `ConversationStatus`, `Notification`, `Report`, `Review`, and `User` are the main entities.
   - The listings domain likely anchors the marketplace workflow: create/edit listings, upload images, geocode locations, mark sold, assign buyer, and manage featured state and moderation.

8. **Authentication and account flows**
   - Authentication is JWT-based with cookies and includes local login/signup plus Google OAuth.
   - Account-related flows include email verification, password reset via 6-digit code, change email with re-verification, profile setup, avatar upload, and account deletion. These are enforced through auth middleware and account-specific controllers.

9. **Marketplace-specific integrations**
   - Image handling uses Cloudinary on both listing and profile flows, with crop support in the client.
   - Maps and location selection use Leaflet/OpenStreetMap in the UI, while server utilities include geocoding helpers and coordinate backfill scripts, indicating location is persisted and normalized in the database.

10. **Admin and moderation boundary**
   - Admin functionality is isolated in both client and server layers.
   - Admin pages cover user management, listing moderation, and report handling, while server-side `adminMiddleware` and admin controllers enforce privileged actions like role changes, blocking, warnings, featured toggles, and force deletes.

11. **Reviews, reports, and trust signals**
   - Reviews are tied to completed sales: only the recorded buyer of a sold listing can review the seller, and seller ratings update as reviews change.
   - Reports and warnings feed moderation workflows, and notifications can be emitted in real time when review or account events occur.

12. **Infrastructure and external services**
   - External dependencies that materially affect the architecture are MongoDB Atlas, Socket.IO, Cloudinary, Resend, and Google OAuth.
   - The repo also includes deployment and environment setup docs, a `Procfile`, and scripts for seeding/verifying data, which suggests the app is built for managed deployment with distinct client/server runtime configuration.

13. **Testing and quality gates**
   - The repository has unit/integration tests on both sides: Jest for client/server logic and Cypress for end-to-end flows.
   - CI checks focus on code style for client and server, which reflects a separation of concerns between frontend and backend codebases rather than a monolithic build pipeline.

Main entry points: [`server/src/routes`](https://github.com/hackyourfutureprojects/c54-final-project-group-b/tree/develop/server/src/routes) (Routes), [`client/src/App.jsx`](https://github.com/hackyourfutureprojects/c54-final-project-group-b/blob/develop/client/src/App.jsx) (Routes), [`server/src/models`](https://github.com/hackyourfutureprojects/c54-final-project-group-b/tree/develop/server/src/models) (Data models), [`client/src/contexts`](https://github.com/hackyourfutureprojects/c54-final-project-group-b/tree/develop/client/src/contexts) (Contexts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client"]
  node_client_shell["App shell<br/>react app<br/>[AppWrapper.jsx]"]
  node_client_routes["Routes<br/>route layer<br/>[App.jsx]"]
  node_client_contexts["Contexts<br/>state layer"]
  node_client_access["Access gates<br/>route guards<br/>[ProtectedRoute.jsx]"]
  node_client_marketplace["Marketplace<br/>buyer flow<br/>[Home.jsx]"]
  node_client_search["Search filters<br/>filter ui<br/>[HeroFilter.jsx]"]
  node_client_listings["Listings<br/>seller flow<br/>[CreateListing.jsx]"]
  node_client_chat["Inbox chat<br/>realtime ui<br/>[Inbox.jsx]"]
  node_client_profile["Profile<br/>account ui<br/>[Profile.jsx]"]
  node_client_admin["Admin UI<br/>moderation ui<br/>[AdminDashboard.jsx]"]
end

subgraph group_server["Server"]
  node_server_app["API app<br/>express app<br/>[app.js]"]
  node_server_routes["Routes"]
  node_server_auth["Auth/account<br/>user domain<br/>[authHandlers.js]"]
  node_server_listings["Listings<br/>marketplace domain<br/>[listing.js]"]
  node_server_messages["Messages<br/>chat domain<br/>[message.js]"]
  node_server_reviews["Reviews<br/>trust domain<br/>[review.js]"]
  node_server_admin["Admin ops<br/>moderation domain<br/>[admin.js]"]
  node_server_socket["Socket layer<br/>realtime server<br/>[socketHandler.js]"]
  node_server_models[("Data models<br/>mongoose models")]
  node_server_utils["Server utils<br/>shared helpers"]
end

subgraph group_infra["Infrastructure"]
  node_infra_db[("MongoDB<br/>database")]
  node_infra_ext(("External services<br/>cloud integrations"))
  node_infra_deploy["Deployment<br/>runtime config"]
end

node_client_shell -->|"renders"| node_client_routes
node_client_shell -->|"provides"| node_client_contexts
node_client_routes -->|"guards"| node_client_access
node_client_routes -->|"serves"| node_client_marketplace
node_client_routes -->|"serves"| node_client_listings
node_client_routes -->|"serves"| node_client_chat
node_client_routes -->|"serves"| node_client_profile
node_client_routes -->|"serves"| node_client_admin
node_client_marketplace -->|"uses"| node_client_search
node_client_chat -->|"uses"| node_client_contexts
node_client_profile -->|"uses"| node_client_contexts
node_client_admin -->|"uses"| node_client_contexts
node_client_marketplace -->|"fetches"| node_server_routes
node_client_listings -->|"writes"| node_server_routes
node_client_chat -->|"connects"| node_server_socket
node_client_profile -->|"updates"| node_server_routes
node_client_admin -->|"moderates"| node_server_admin
node_server_app -->|"mounts"| node_server_routes
node_server_routes -->|"dispatches"| node_server_auth
node_server_routes -->|"dispatches"| node_server_listings
node_server_routes -->|"dispatches"| node_server_messages
node_server_routes -->|"dispatches"| node_server_reviews
node_server_routes -->|"dispatches"| node_server_admin
node_server_routes -->|"reads/writes"| node_server_models
node_server_auth -->|"uses"| node_server_utils
node_server_listings -->|"uses"| node_server_utils
node_server_messages -->|"emits"| node_server_socket
node_server_reviews -->|"updates"| node_server_models
node_server_admin -->|"updates"| node_server_models
node_server_models -->|"persists"| node_infra_db
node_server_auth -->|"auth/email"| node_infra_ext
node_server_listings -->|"media/location"| node_infra_ext
node_server_socket -->|"realtime"| node_infra_ext
node_infra_deploy -->|"starts"| node_server_app
node_infra_deploy -->|"serves"| node_client_shell

click node_client_shell "https://github.com/hackyourfutureprojects/c54-final-project-group-b/blob/develop/client/src/AppWrapper.jsx"
click node_client_routes "https://github.com/hackyourfutureprojects/c54-final-project-group-b/blob/develop/client/src/App.jsx"
click node_client_contexts "https://github.com/hackyourfutureprojects/c54-final-project-group-b/tree/develop/client/src/contexts"
click node_client_access "https://github.com/hackyourfutureprojects/c54-final-project-group-b/blob/develop/client/src/components/ProtectedRoute.jsx"
click node_client_marketplace "https://github.com/hackyourfutureprojects/c54-final-project-group-b/blob/develop/client/src/pages/Home/Home.jsx"
click node_client_search "https://github.com/hackyourfutureprojects/c54-final-project-group-b/blob/develop/client/src/components/HeroFilter/HeroFilter.jsx"
click node_client_listings "https://github.com/hackyourfutureprojects/c54-final-project-group-b/blob/develop/client/src/pages/CreateListing/CreateListing.jsx"
click node_client_chat "https://github.com/hackyourfutureprojects/c54-final-project-group-b/blob/develop/client/src/pages/Inbox/Inbox.jsx"
click node_client_profile "https://github.com/hackyourfutureprojects/c54-final-project-group-b/blob/develop/client/src/pages/Profile/Profile.jsx"
click node_client_admin "https://github.com/hackyourfutureprojects/c54-final-project-group-b/blob/develop/client/src/pages/Admin/AdminDashboard.jsx"
click node_server_app "https://github.com/hackyourfutureprojects/c54-final-project-group-b/blob/develop/server/src/app.js"
click node_server_routes "https://github.com/hackyourfutureprojects/c54-final-project-group-b/tree/develop/server/src/routes"
click node_server_auth "https://github.com/hackyourfutureprojects/c54-final-project-group-b/blob/develop/server/src/controllers/user/authHandlers.js"
click node_server_listings "https://github.com/hackyourfutureprojects/c54-final-project-group-b/blob/develop/server/src/controllers/listing.js"
click node_server_messages "https://github.com/hackyourfutureprojects/c54-final-project-group-b/blob/develop/server/src/controllers/message.js"
click node_server_reviews "https://github.com/hackyourfutureprojects/c54-final-project-group-b/blob/develop/server/src/controllers/review.js"
click node_server_admin "https://github.com/hackyourfutureprojects/c54-final-project-group-b/blob/develop/server/src/controllers/admin.js"
click node_server_socket "https://github.com/hackyourfutureprojects/c54-final-project-group-b/blob/develop/server/src/socket/socketHandler.js"
click node_server_models "https://github.com/hackyourfutureprojects/c54-final-project-group-b/tree/develop/server/src/models"
click node_server_utils "https://github.com/hackyourfutureprojects/c54-final-project-group-b/tree/develop/server/src/utils"
click node_infra_deploy "https://github.com/hackyourfutureprojects/c54-final-project-group-b/tree/develop/Procfile"

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_client_shell,node_client_routes,node_client_contexts,node_client_access,node_client_marketplace,node_client_search,node_client_listings,node_client_chat,node_client_profile,node_client_admin toneBlue
class node_server_app,node_server_routes,node_server_auth,node_server_listings,node_server_messages,node_server_reviews,node_server_admin,node_server_socket,node_server_models,node_server_utils toneAmber
class node_infra_db,node_infra_ext,node_infra_deploy toneMint
```

## Components

### Client

React/Vite frontend

- [App shell](https://github.com/hackyourfutureprojects/c54-final-project-group-b/blob/develop/client/src/AppWrapper.jsx): react app · Bootstraps providers, routing, and global UI state · `client/src/AppWrapper.jsx`
- [Routes](https://github.com/hackyourfutureprojects/c54-final-project-group-b/blob/develop/client/src/App.jsx): route layer · Top-level pages for marketplace, account, auth, and admin · `client/src/App.jsx`
- [Contexts](https://github.com/hackyourfutureprojects/c54-final-project-group-b/tree/develop/client/src/contexts): state layer · Auth, theme, notifications, toasts, and socket state · `client/src/contexts`
- [Access gates](https://github.com/hackyourfutureprojects/c54-final-project-group-b/blob/develop/client/src/components/ProtectedRoute.jsx): route guards · Protected, public-only, admin, and role-based boundaries · `client/src/components/ProtectedRoute.jsx`
- [Marketplace](https://github.com/hackyourfutureprojects/c54-final-project-group-b/blob/develop/client/src/pages/Home/Home.jsx): buyer flow · Home, listing detail, favorites, and listing cards · `client/src/pages/Home/Home.jsx`
- [Search filters](https://github.com/hackyourfutureprojects/c54-final-project-group-b/blob/develop/client/src/components/HeroFilter/HeroFilter.jsx): filter ui · Hero search, chips, ranges, and city filtering · `client/src/components/HeroFilter/HeroFilter.jsx`
- [Listings](https://github.com/hackyourfutureprojects/c54-final-project-group-b/blob/develop/client/src/pages/CreateListing/CreateListing.jsx): seller flow · Create, edit, and manage listings with image and form steps · `client/src/pages/CreateListing/CreateListing.jsx`
- [Inbox chat](https://github.com/hackyourfutureprojects/c54-final-project-group-b/blob/develop/client/src/pages/Inbox/Inbox.jsx): realtime ui · Inbox and conversation screens driven by socket state · `client/src/pages/Inbox/Inbox.jsx`
- [Profile](https://github.com/hackyourfutureprojects/c54-final-project-group-b/blob/develop/client/src/pages/Profile/Profile.jsx): account ui · Profile view, setup, settings, and avatar flow · `client/src/pages/Profile/Profile.jsx`
- [Admin UI](https://github.com/hackyourfutureprojects/c54-final-project-group-b/blob/develop/client/src/pages/Admin/AdminDashboard.jsx): moderation ui · User, listing, and report management screens · `client/src/pages/Admin/AdminDashboard.jsx`

### Server

Express API and realtime backend

- [API app](https://github.com/hackyourfutureprojects/c54-final-project-group-b/blob/develop/server/src/app.js): express app · Express application composition and startup · `server/src/app.js`
- [Routes](https://github.com/hackyourfutureprojects/c54-final-project-group-b/tree/develop/server/src/routes): http routes · Domain routes for auth, listings, messages, favorites, notifications, reviews, reports, admin, and email · `server/src/routes`
- [Auth/account](https://github.com/hackyourfutureprojects/c54-final-project-group-b/blob/develop/server/src/controllers/user/authHandlers.js): user domain · Login, signup, OAuth, verification, password reset, profile, and account lifecycle · `server/src/controllers/user/authHandlers.js`
- [Listings](https://github.com/hackyourfutureprojects/c54-final-project-group-b/blob/develop/server/src/controllers/listing.js): marketplace domain · Listing CRUD, image/location handling, sold state, and moderation hooks · `server/src/controllers/listing.js`
- [Messages](https://github.com/hackyourfutureprojects/c54-final-project-group-b/blob/develop/server/src/controllers/message.js): chat domain · Conversations, messages, unread state, and realtime-facing message APIs · `server/src/controllers/message.js`
- [Reviews](https://github.com/hackyourfutureprojects/c54-final-project-group-b/blob/develop/server/src/controllers/review.js): trust domain · Sale-bound reviews and seller rating updates · `server/src/controllers/review.js`
- [Admin ops](https://github.com/hackyourfutureprojects/c54-final-project-group-b/blob/develop/server/src/controllers/admin.js): moderation domain · Privilege checks, role changes, blocking, warnings, featured toggles, and forced actions · `server/src/controllers/admin.js`
- [Socket layer](https://github.com/hackyourfutureprojects/c54-final-project-group-b/blob/develop/server/src/socket/socketHandler.js): realtime server · Socket.IO connection handling for live chat and notifications · `server/src/socket/socketHandler.js`
- [Data models](https://github.com/hackyourfutureprojects/c54-final-project-group-b/tree/develop/server/src/models): mongoose models · User, Listing, Favorite, Message, Notification, Report, Review, and ConversationStatus · `server/src/models`
- [Server utils](https://github.com/hackyourfutureprojects/c54-final-project-group-b/tree/develop/server/src/utils): shared helpers · Validation, geocoding, logging, listing helpers, and email service · `server/src/utils`

### Infrastructure

External services and deployment

- **MongoDB**: database · System of record for users, listings, conversations, reviews, and moderation data
- **External services**: cloud integrations · Cloudinary, Resend, Google OAuth, and Socket.IO transport
- [Deployment](https://github.com/hackyourfutureprojects/c54-final-project-group-b/tree/develop/Procfile): runtime config · Managed deployment, environment setup, and seed scripts · `Procfile`

## Connections

- App shell → Routes: renders · App shell mounts the routed application
- App shell → Contexts: provides · Global providers wrap the UI
- Routes → Access gates: guards · Routes are filtered by auth and role
- Routes → Marketplace: serves · Primary browsing and detail journeys
- Routes → Listings: serves · Seller listing creation and editing
- Routes → Inbox chat: serves · Inbox and conversation views
- Routes → Profile: serves · Account and profile screens
- Routes → Admin UI: serves · Admin-only management screens
- Marketplace → Search filters: uses · Search and filter subsystem shapes discovery
- Inbox chat → Contexts: uses · Socket and notification state
- Profile → Contexts: uses · Auth and settings state
- Admin UI → Contexts: uses · Admin UI depends on authenticated user state
- Marketplace → Routes: fetches · Marketplace data comes from REST APIs
- Listings → Routes: writes · Create and edit flows persist through the API
- Inbox chat → Socket layer: connects · Live chat and unread updates use sockets
- Profile → Routes: updates · Profile, security, and account actions
- Admin UI → Admin ops: moderates · Admin screens map to privileged backend actions
- API app → Routes: mounts · Express app composes domain routers
- Routes → Auth/account: dispatches · Auth and account endpoints
- Routes → Listings: dispatches · Listing endpoints
- Routes → Messages: dispatches · Message and inbox endpoints
- Routes → Reviews: dispatches · Review endpoints
- Routes → Admin ops: dispatches · Admin endpoints
- Routes → Data models: reads/writes · Route handlers persist through the data layer
- Auth/account → Server utils: uses · Validation, email, and helper utilities
- Listings → Server utils: uses · Geocoding, listing helpers, and validation
- Messages → Socket layer: emits · Message changes drive realtime events
- Reviews → Data models: updates · Review writes affect seller ratings and sale records
- Admin ops → Data models: updates · Moderation actions change users, listings, and reports
- Data models → MongoDB: persists · Mongoose stores application state in MongoDB
- Auth/account → External services: auth/email · Google OAuth and verification email flows
- Listings → External services: media/location · Cloudinary and geocoding integrations
- Socket layer → External services: realtime · Socket.IO transport provides live updates
- Deployment → API app: starts · Procfile and deployment runtime boot the API
- Deployment → App shell: serves · Deployment also serves the frontend build