# ayhanarashtasin/artisanaura architecture

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

- Interactive diagram: https://gitdiagram.com/ayhanarashtasin/artisanaura
- Repository: https://github.com/ayhanarashtasin/artisanaura

## Overview

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: [`frontend/src/api/client.js`](https://github.com/ayhanarashtasin/artisanaura/blob/main/frontend/src/api/client.js) (API client), [`frontend/src/App.jsx`](https://github.com/ayhanarashtasin/artisanaura/blob/main/frontend/src/App.jsx) (SPA shell), [`backend/index.js`](https://github.com/ayhanarashtasin/artisanaura/blob/main/backend/index.js) (API server), [`backend/config/database.js`](https://github.com/ayhanarashtasin/artisanaura/blob/main/backend/config/database.js) (Mongo DB)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_backend_index["API server<br/>Express entrypoint<br/>[index.js]"]
  node_backend_db[("Mongo DB<br/>Mongoose connection<br/>[database.js]")]
  node_backend_routes["API routes<br/>HTTP routes"]
  node_backend_controllers["Controllers<br/>request handlers"]
  node_backend_services["Services<br/>business logic"]
  node_backend_models[("Models<br/>Mongoose schemas")]
  node_backend_validation["Validation<br/>middleware<br/>[validation.js]"]
  node_backend_auth["Auth<br/>account/session"]
  node_backend_catalog["Catalog<br/>products/shop"]
  node_backend_checkout["Checkout<br/>payments"]
  node_backend_orders["Orders<br/>order lifecycle"]
  node_backend_reviews["Reviews<br/>ratings/media"]
  node_backend_support["Support<br/>help requests"]
  node_backend_admin["Admin<br/>platform ops"]
  node_backend_chatbot["Chatbot<br/>AI integration"]
end

subgraph group_frontend["Frontend"]
  node_frontend_app["SPA shell<br/>React/Vite entry<br/>[App.jsx]"]
  node_frontend_client["API client<br/>HTTP layer<br/>[client.js]"]
  node_frontend_state["App state<br/>contexts"]
  node_frontend_shared["Shared UI<br/>common components"]
  node_frontend_features["Feature views<br/>feature folders"]
  node_frontend_pages["Pages"]
end

node_backend_index -->|"mounts"| node_backend_routes
node_backend_index -->|"connects"| node_backend_db
node_backend_routes -.->|"guards"| node_backend_validation
node_backend_routes -->|"dispatches"| node_backend_controllers
node_backend_controllers -->|"delegates"| node_backend_services
node_backend_services -->|"persists"| node_backend_models
node_backend_auth -->|"uses"| node_backend_services
node_backend_catalog -->|"uses"| node_backend_services
node_backend_checkout -->|"uses"| node_backend_services
node_backend_orders -->|"uses"| node_backend_services
node_backend_reviews -->|"uses"| node_backend_services
node_backend_support -->|"uses"| node_backend_services
node_backend_admin -->|"uses"| node_backend_services
node_backend_chatbot -->|"uses"| node_backend_services
node_backend_auth -->|"auth data"| node_backend_models
node_backend_catalog -->|"catalog data"| node_backend_models
node_backend_checkout -->|"creates"| node_backend_orders
node_backend_reviews -->|"review data"| node_backend_models
node_backend_support -->|"support data"| node_backend_models
node_frontend_app -->|"composes"| node_frontend_shared
node_frontend_app -->|"renders"| node_frontend_features
node_frontend_app -->|"routes"| node_frontend_pages
node_frontend_state -->|"drives"| node_frontend_client
node_frontend_features -->|"calls"| node_frontend_client
node_frontend_pages -->|"calls"| node_frontend_client
node_frontend_client -->|"HTTP API"| node_backend_routes
node_frontend_shared -.->|"protects"| node_backend_admin

click node_backend_index "https://github.com/ayhanarashtasin/artisanaura/blob/main/backend/index.js"
click node_backend_db "https://github.com/ayhanarashtasin/artisanaura/blob/main/backend/config/database.js"
click node_backend_validation "https://github.com/ayhanarashtasin/artisanaura/blob/main/backend/middleware/validation.js"
click node_frontend_app "https://github.com/ayhanarashtasin/artisanaura/blob/main/frontend/src/App.jsx"
click node_frontend_client "https://github.com/ayhanarashtasin/artisanaura/blob/main/frontend/src/api/client.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_backend_index,node_backend_db,node_backend_routes,node_backend_controllers,node_backend_services,node_backend_models,node_backend_validation,node_backend_auth,node_backend_catalog,node_backend_checkout,node_backend_orders,node_backend_reviews,node_backend_support,node_backend_admin,node_backend_chatbot toneBlue
class node_frontend_app,node_frontend_client,node_frontend_state,node_frontend_shared,node_frontend_features,node_frontend_pages toneAmber
```

## Components

### Backend

Express API, business logic, persistence, and integrations.

- [API server](https://github.com/ayhanarashtasin/artisanaura/blob/main/backend/index.js): Express entrypoint · Bootstraps the backend runtime, middleware, routes, and database connection. · `backend/index.js`
- [Mongo DB](https://github.com/ayhanarashtasin/artisanaura/blob/main/backend/config/database.js): Mongoose connection · Database configuration and connection setup for the MongoDB datastore. · `backend/config/database.js`
- **API routes**: HTTP routes · Route layer exposing auth, catalog, checkout, orders, reviews, support, chatbot, and admin endpoints.
- **Controllers**: request handlers · Request/response orchestration layer for domain actions.
- **Services**: business logic · Core business rules for accounts, products, checkout, orders, reviews, help requests, admin, and chat.
- **Models**: Mongoose schemas · Persistent domain models for users, products, orders, reviews, and help requests.
- [Validation](https://github.com/ayhanarashtasin/artisanaura/blob/main/backend/middleware/validation.js): middleware · Request validation boundary before controllers and services execute. · `backend/middleware/validation.js`
- **Auth**: account/session · Registration, login, token issuance, refresh-cookie session continuity, and account lifecycle.
- **Catalog**: products/shop · Product browsing, shop profiles, seller inventory, search, and CRUD operations.
- **Checkout**: payments · Stripe-backed payment entry point and order confirmation flow.
- **Orders**: order lifecycle · Buyer history, seller management, status updates, and order analytics.
- **Reviews**: ratings/media · Product and shop review flows, including image uploads.
- **Support**: help requests · Help/dispute request submission and admin moderation of request status.
- **Admin**: platform ops · Metrics and moderation surface across users, products, orders, reviews, and help requests.
- **Chatbot**: AI integration · Gemini-powered chat and image-aware prompt handling, plus AI-assisted content generation.

### Frontend

React/Vite single-page app and UI state.

- [SPA shell](https://github.com/ayhanarashtasin/artisanaura/blob/main/frontend/src/App.jsx): React/Vite entry · Main application entry and route composition for the client app. · `frontend/src/App.jsx`
- [API client](https://github.com/ayhanarashtasin/artisanaura/blob/main/frontend/src/api/client.js): HTTP layer · Centralized browser client with bearer auth, refresh handling, and domain API wrappers. · `frontend/src/api/client.js`
- **App state**: contexts · Global state for auth, cart, theme, and notifications.
- **Shared UI**: common components · Reusable header, toast, confirm dialog, chatbot launcher, and admin route guard.
- **Feature views**: feature folders · Feature-specific screens for auth, cart, products, user dashboard, and admin.
- **Pages**: route pages · Top-level pages for home, search, shop details, category views, and checkout outcomes.

## Connections

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