How hackyourfutureprojects/c54-final-project-group-b works
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: routes Routes · App.jsx Routes · models Data models · contexts Contexts
Components 23
Client
React/Vite frontend
- App shell · Bootstraps providers, routing, and global UI state
client/src/AppWrapper.jsx - Routes · Top-level pages for marketplace, account, auth, and admin
client/src/App.jsx - Contexts · Auth, theme, notifications, toasts, and socket state
client/src/contexts - Access gates · Protected, public-only, admin, and role-based boundaries
client/src/components/ProtectedRoute.jsx - Marketplace · Home, listing detail, favorites, and listing cards
client/src/pages/Home/Home.jsx - Search filters · Hero search, chips, ranges, and city filtering
client/src/components/HeroFilter/HeroFilter.jsx - Listings · Create, edit, and manage listings with image and form steps
client/src/pages/CreateListing/CreateListing.jsx - Inbox chat · Inbox and conversation screens driven by socket state
client/src/pages/Inbox/Inbox.jsx - Profile · Profile view, setup, settings, and avatar flow
client/src/pages/Profile/Profile.jsx - Admin UI · User, listing, and report management screens
client/src/pages/Admin/AdminDashboard.jsx
Server
Express API and realtime backend
- API app · Express application composition and startup
server/src/app.js - Routes · Domain routes for auth, listings, messages, favorites, notifications, reviews, reports, admin, and email
server/src/routes - Auth/account · Login, signup, OAuth, verification, password reset, profile, and account lifecycle
server/src/controllers/user/authHandlers.js - Listings · Listing CRUD, image/location handling, sold state, and moderation hooks
server/src/controllers/listing.js - Messages · Conversations, messages, unread state, and realtime-facing message APIs
server/src/controllers/message.js - Reviews · Sale-bound reviews and seller rating updates
server/src/controllers/review.js - Admin ops · Privilege checks, role changes, blocking, warnings, featured toggles, and forced actions
server/src/controllers/admin.js - Socket layer · Socket.IO connection handling for live chat and notifications
server/src/socket/socketHandler.js - Data models · User, Listing, Favorite, Message, Notification, Report, Review, and ConversationStatus
server/src/models - Server utils · Validation, geocoding, logging, listing helpers, and email service
server/src/utils
Infrastructure
External services and deployment
- MongoDB · System of record for users, listings, conversations, reviews, and moderation data
- External services · Cloudinary, Resend, Google OAuth, and Socket.IO transport
- Deployment · Managed deployment, environment setup, and seed scripts
Procfile
Connections 35
- 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