How ayhanarashtasin/artisanaura works
1. High-level shape
- This is a two-app monorepo: a Node.js/Express backend and a React/Vite frontend.
- The backend is the system of record: it owns authentication, persistence, payments, orders, reviews, support tickets, and AI/chatbot calls.
- The frontend is a single-page app that consumes the backend API and organizes the UI by feature area.
2. Backend layering
- The backend follows a clear route → controller → service → model pattern.
- routes/ defines HTTP endpoints, controllers/ handles request/response orchestration, services/ contains business logic, and models/ defines MongoDB schemas via Mongoose.
- middleware/validation.js suggests request validation is enforced before business logic runs.
3. Core domain data
- The persistent domain is centered on five main MongoDB models: User, Product, Order, Review, HelpRequest.
- These models represent the key business entities that flow through the rest of the system: catalog, checkout, post-purchase activity, ratings, and support.
4. Authentication and session management
- authController, authService, and authRoutes implement registration/login and account lifecycle actions.
- The app uses JWT access tokens plus refresh tokens in HTTP-only cookies; the frontend stores the access token and refreshes on 401.
- This creates a split between short-lived API authorization and longer-lived browser session continuity.
5. Product, shop, and catalog access
- product* and shop* modules handle the seller-facing catalog and public browsing experience.
- Products are exposed through category/search endpoints, seller-specific “my shop” views, and CRUD operations for sellers/admins.
- Shop endpoints separate a seller’s public profile from their private editable shop state.
6. Checkout and order lifecycle
- checkoutController / checkoutService is the payment entry point and integrates with Stripe.
- After payment, the frontend/backend flow returns to the app via success/cancel pages, and the backend confirms the order through an order endpoint.
- order* modules then support buyer order history and seller order management, including status updates and analytics/stats endpoints.
7. Reviews and support
- review* handles product and shop reviews, including image uploads for richer feedback.
- help* models the support/dispute lane: users submit help requests, and admins can review and change their status.
- These are separate from orders, but they are tied to the same user/product/seller ecosystem.
8. Admin boundary
- adminController, adminService, and adminRoutes provide a platform-management surface for metrics and moderation.
- Admin functions cover users, products, orders, reviews, and help requests.
- The frontend enforces this boundary with AdminRoute.jsx, so admin UI is gated separately from normal buyer/seller pages.
9. AI/chatbot and external services
- chatbotController / chatbotService integrate with Gemini API for chat and image-aware prompts.
- The README also notes AI-assisted product description generation, so AI is treated as a backend capability rather than a frontend-only feature.
- Other external integrations that materially affect architecture are MongoDB, Stripe, and SMTP/Nodemailer for account and support emails.
10. File uploads and static assets
- The backend serves uploaded files from /uploads, and the README indicates Multer is used for product and review images.
- Product creation uses a single image field; review creation supports multiple images.
- This means media is stored separately from MongoDB documents, but referenced by the domain records.
11. Frontend app structure
- The frontend is organized by contexts, API clients, shared components, feature folders, and pages.
- contexts/ holds app-wide state for auth, cart, dark mode, and notifications.
- features/ and pages/ split the UI by business area: authentication, cart, products, user dashboard, checkout outcomes, search, shop details, etc.
12. Frontend-to-backend data flow
- src/api/client.js is the central HTTP client; domain API files wrap it for auth, products, checkout, orders, reviews, admin, and help.
- Requests attach the bearer access token; on expiry the app calls the refresh endpoint and retries.
- This keeps authentication behavior centralized and avoids each screen managing token logic independently.
13. UI composition and route protection
- Shared UI lives in components/common/ for global elements like header, toast, confirm dialog, chatbot launcher, and admin route protection.
- Feature screens use these shared primitives rather than duplicating layout or state logic.
- The app is thus split between reusable shell components and business-specific pages.
14. Deployment/runtime boundary
- The repository is meant to run as two separate dev servers: backend on port 3000 and frontend on Vite’s dev server.
- The frontend targets the backend API base URL directly; the backend must allow CORS with credentials because refresh cookies are part of the auth design.
- In a diagram, treat the backend as the API/auth/payment/data layer and the frontend as the presentation layer consuming it over HTTP.
Main entry points: client.js API client · App.jsx SPA shell · index.js API server · database.js Mongo DB
Components 21
Backend
Express API, business logic, persistence, and integrations.
- API server · Bootstraps the backend runtime, middleware, routes, and database connection.
backend/index.js - Mongo DB · Database configuration and connection setup for the MongoDB datastore.
backend/config/database.js - API routes · Route layer exposing auth, catalog, checkout, orders, reviews, support, chatbot, and admin endpoints.
- Controllers · Request/response orchestration layer for domain actions.
- Services · Core business rules for accounts, products, checkout, orders, reviews, help requests, admin, and chat.
- Models · Persistent domain models for users, products, orders, reviews, and help requests.
- Validation · Request validation boundary before controllers and services execute.
backend/middleware/validation.js - Auth · Registration, login, token issuance, refresh-cookie session continuity, and account lifecycle.
- Catalog · Product browsing, shop profiles, seller inventory, search, and CRUD operations.
- Checkout · Stripe-backed payment entry point and order confirmation flow.
- Orders · Buyer history, seller management, status updates, and order analytics.
- Reviews · Product and shop review flows, including image uploads.
- Support · Help/dispute request submission and admin moderation of request status.
- Admin · Metrics and moderation surface across users, products, orders, reviews, and help requests.
- Chatbot · Gemini-powered chat and image-aware prompt handling, plus AI-assisted content generation.
Frontend
React/Vite single-page app and UI state.
- SPA shell · Main application entry and route composition for the client app.
frontend/src/App.jsx - API client · Centralized browser client with bearer auth, refresh handling, and domain API wrappers.
frontend/src/api/client.js - App state · Global state for auth, cart, theme, and notifications.
- Shared UI · Reusable header, toast, confirm dialog, chatbot launcher, and admin route guard.
- Feature views · Feature-specific screens for auth, cart, products, user dashboard, and admin.
- Pages · Top-level pages for home, search, shop details, category views, and checkout outcomes.
Connections 27
- API server → API routes: mounts · Registers all HTTP route groups on the server.
- API server → Mongo DB: connects · Initializes the MongoDB connection.
- API routes → Validation: guards · Applies validation before request handling.
- API routes → Controllers: dispatches · Routes forward requests to controllers.
- Controllers → Services: delegates · Controllers hand business operations to services.
- Services → Models: persists · Services read and write MongoDB models.
- Auth → Services: uses · Auth logic is implemented in the service layer.
- Catalog → Services: uses · Product and shop workflows are handled in services.
- Checkout → Services: uses · Checkout service coordinates payment and order creation.
- Orders → Services: uses · Order history, status, and analytics run through services.
- Reviews → Services: uses · Review creation and retrieval are handled in services.
- Support → Services: uses · Help request workflows are handled in services.
- Admin → Services: uses · Admin moderation and metrics are backed by services.
- Chatbot → Services: uses · Chat and AI generation are implemented in services.
- Auth → Models: auth data · User accounts and session-related persistence.
- Catalog → Models: catalog data · Product and shop state persisted through models.
- Checkout → Orders: creates · Successful payment flows into order confirmation.
- Reviews → Models: review data · Reviews and review images are stored through models and uploads.
- Support → Models: support data · Help requests are persisted for admin review.
- SPA shell → Shared UI: composes · Main app uses shared shell and protection components.
- SPA shell → Feature views: renders · Feature screens are assembled into the app.
- SPA shell → Pages: routes · Top-level pages are mounted as navigation targets.
- App state → API client: drives · Contexts rely on the API client for auth and data interactions.
- Feature views → API client: calls · Feature views use API wrappers to talk to the backend.
- Pages → API client: calls · Pages fetch domain data through the centralized client.
- API client → API routes: HTTP API · Browser app consumes the backend endpoints over HTTP.
- Shared UI → Admin: protects · Admin route guard enforces the admin boundary in the UI.