# guywithnogirl/capybara_frontend architecture

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

- Interactive diagram: https://gitdiagram.com/guywithnogirl/capybara_frontend
- Repository: https://github.com/guywithnogirl/capybara_frontend

## Overview

#### Purpose and Runtime
This is a Vite-served React single-page storefront client. It provides product browsing, account authentication, cart and wishlist management, checkout/payment, address management, and order history/detail views. The README is template-level; the application structure indicates a backend API is consumed through service modules.

Entry points: `index.html`, `src/main.jsx`, and `src/App.jsx`. Vite configuration is in `vite.config.js`.

#### Application Composition and Navigation
`src/App.jsx` is the application shell and likely owns route composition between public catalog pages and authenticated commerce/account flows. `src/main.jsx` mounts React and global styles (`src/index.css`); `src/App.css` supplies app-level presentation.

Page-level features are organized under `src/pages`, including catalog (`Home.jsx`, `Shop.jsx`, `ProductDetail.jsx`), customer account (`Account.jsx`, `AddressBook.jsx`), and purchase lifecycle (`Cart.jsx`, `Checkout.jsx`, `Payment.jsx`, `OrderSuccess.jsx`, `OrderHistory.jsx`, `OrderDetails.jsx`).

#### Shared Client State
Three React contexts define the main cross-page state boundaries:
- Authentication and current-user/session state: `src/context/AuthContext.jsx`, with JWT parsing in `src/context/jwtDecode.js`.
- Cart state and cart synchronization: `src/context/CartContext.jsx`.
- Saved-product state: `src/context/WishlistContext.jsx`.

These contexts let catalog, navigation, account, and checkout UI consume shared state without direct page-to-page coupling.

#### Authentication and Access Control
Authentication views are `src/pages/Login.jsx`, `src/pages/Register.jsx`, `src/pages/ForgotPassword.jsx`, and `src/pages/ResetPassword.jsx`. API operations are isolated in `src/services/authService.js`.

`src/components/ProtectedRoute.jsx` is the access-control boundary for customer-only routes such as account, address book, and order-related pages. It should depend on `AuthContext`, rather than individual pages interpreting tokens themselves.

#### Commerce Flow
Product discovery flows from home/shop listings to product detail, using reusable cards and ratings: `src/pages/Home.jsx`, `src/pages/Shop.jsx`, `src/pages/ProductDetail.jsx`, `src/components/ProductCard.jsx`, and `src/components/StarRating.jsx`.

The purchase path is cart → checkout → payment → success/order record: `src/pages/Cart.jsx`, `src/pages/Checkout.jsx`, `src/pages/Payment.jsx`, and `src/pages/OrderSuccess.jsx`. Historic orders and fulfillment details are presented through `src/pages/OrderHistory.jsx` and `src/pages/OrderDetails.jsx`.

#### API and Data Boundaries
`src/services/api.js` is the common HTTP integration boundary. Domain-specific service adapters separate backend calls from UI:
- Catalog/content: `src/services/productService.js`, `src/services/categoryService.js`, `src/services/bannerService.js`, `src/services/reviewService.js`.
- Customer commerce data: `src/services/cartService.js`, `src/services/wishlistService.js`, `src/services/orderService.js`, `src/services/addressService.js`.
- Identity: `src/services/authService.js`.

`src/data/products.js` may provide local catalog seed/fallback data, distinct from backend product retrieval.

#### Shared UI and Deployment
Global chrome and reusable interaction elements are centralized in `src/components/Navbar.jsx`, `src/components/Footer.jsx`, `src/components/Spinner.jsx`, and `src/components/Return.jsx`. CSS modules colocated with components/pages provide scoped styling.

The frontend is built and deployed via GitHub Actions at `.github/workflows/deploy.yml`. Static/public assets are supplied from `public/assets` and bundled application assets from `src/assets`; no backend runtime or payment provider implementation is present in this repository.

Main entry points: [`src/services/cartService.js`](https://github.com/guywithnogirl/capybara_frontend/blob/main/src/services/cartService.js) (Commerce services), [`src/App.jsx`](https://github.com/guywithnogirl/capybara_frontend/blob/main/src/App.jsx) (App shell), [`src/components/ProtectedRoute.jsx`](https://github.com/guywithnogirl/capybara_frontend/blob/main/src/components/ProtectedRoute.jsx) (Protected route), [`src/pages/Home.jsx`](https://github.com/guywithnogirl/capybara_frontend/blob/main/src/pages/Home.jsx) (Catalog pages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Client Runtime"]
  node_vite{{"Vite host<br/>build runtime<br/>[vite.config.js]"}}
  node_main["React entry<br/>bootstrap<br/>[main.jsx]"]
  node_app["App shell<br/>route composition<br/>[App.jsx]"]
end

subgraph group_ui["Pages &amp; UI"]
  node_catalog["Catalog pages<br/>page feature<br/>[Home.jsx]"]
  node_account["Account pages<br/>page feature<br/>[Account.jsx]"]
  node_purchase["Purchase flow<br/>page feature<br/>[Cart.jsx]"]
  node_orders["Order views<br/>page feature<br/>[OrderHistory.jsx]"]
  node_auth_views["Auth views<br/>page feature<br/>[Login.jsx]"]
  node_shared_ui["Shared UI<br/>component layer<br/>[Navbar.jsx]"]
  node_protected_route["Protected route<br/>access control<br/>[ProtectedRoute.jsx]"]
end

subgraph group_state["Shared State"]
  node_auth_context["Auth context<br/>React context<br/>[AuthContext.jsx]"]
  node_cart_context["Cart context<br/>React context<br/>[CartContext.jsx]"]
  node_wishlist_context["Wishlist context<br/>React context"]
end

subgraph group_services["API Integration"]
  node_api{{"HTTP API client<br/>integration boundary<br/>[api.js]"}}
  node_catalog_services["Catalog services<br/>service adapters<br/>[productService.js]"]
  node_commerce_services["Commerce services<br/>service adapters<br/>[cartService.js]"]
  node_identity_service["Auth service<br/>service adapter<br/>[authService.js]"]
  node_backend[("Backend API<br/>external system")]
end

subgraph group_delivery["Delivery"]
  node_deployment["GitHub Pages deployment<br/>CI/CD workflow<br/>[deploy.yml]"]
end

node_vite -->|"serves/builds"| node_main
node_main -->|"mounts"| node_app
node_app -->|"routes to"| node_catalog
node_app -->|"routes to"| node_auth_views
node_app -->|"guards routes through"| node_protected_route
node_protected_route -->|"permits"| node_account
node_protected_route -->|"permits"| node_purchase
node_protected_route -->|"permits"| node_orders
node_protected_route -->|"checks"| node_auth_context
node_app -->|"uses"| node_shared_ui
node_catalog -->|"loads catalog"| node_catalog_services
node_catalog -->|"adds items"| node_cart_context
node_catalog -->|"saves items"| node_wishlist_context
node_auth_views -->|"authenticates via"| node_identity_service
node_identity_service -->|"uses"| node_api
node_auth_context -->|"manages session via"| node_identity_service
node_purchase -->|"reads cart"| node_cart_context
node_purchase -->|"creates order"| node_commerce_services
node_orders -->|"loads orders"| node_commerce_services
node_account -->|"manages addresses"| node_commerce_services
node_cart_context -->|"synchronizes cart"| node_commerce_services
node_wishlist_context -->|"synchronizes wishlist"| node_commerce_services
node_catalog_services -->|"uses"| node_api
node_commerce_services -->|"uses"| node_api
node_api -->|"HTTP requests"| node_backend
node_deployment -->|"builds and deploys"| node_vite

click node_vite "https://github.com/guywithnogirl/capybara_frontend/blob/main/vite.config.js"
click node_main "https://github.com/guywithnogirl/capybara_frontend/blob/main/src/main.jsx"
click node_app "https://github.com/guywithnogirl/capybara_frontend/blob/main/src/App.jsx"
click node_catalog "https://github.com/guywithnogirl/capybara_frontend/blob/main/src/pages/Home.jsx"
click node_account "https://github.com/guywithnogirl/capybara_frontend/blob/main/src/pages/Account.jsx"
click node_purchase "https://github.com/guywithnogirl/capybara_frontend/blob/main/src/pages/Cart.jsx"
click node_orders "https://github.com/guywithnogirl/capybara_frontend/blob/main/src/pages/OrderHistory.jsx"
click node_auth_views "https://github.com/guywithnogirl/capybara_frontend/blob/main/src/pages/Login.jsx"
click node_shared_ui "https://github.com/guywithnogirl/capybara_frontend/blob/main/src/components/Navbar.jsx"
click node_protected_route "https://github.com/guywithnogirl/capybara_frontend/blob/main/src/components/ProtectedRoute.jsx"
click node_auth_context "https://github.com/guywithnogirl/capybara_frontend/blob/main/src/context/AuthContext.jsx"
click node_cart_context "https://github.com/guywithnogirl/capybara_frontend/blob/main/src/context/CartContext.jsx"
click node_wishlist_context "https://github.com/guywithnogirl/capybara_frontend/blob/main/src/context/WishlistContext.jsx"
click node_api "https://github.com/guywithnogirl/capybara_frontend/blob/main/src/services/api.js"
click node_catalog_services "https://github.com/guywithnogirl/capybara_frontend/blob/main/src/services/productService.js"
click node_commerce_services "https://github.com/guywithnogirl/capybara_frontend/blob/main/src/services/cartService.js"
click node_identity_service "https://github.com/guywithnogirl/capybara_frontend/blob/main/src/services/authService.js"
click node_deployment "https://github.com/guywithnogirl/capybara_frontend/blob/main/.github/workflows/deploy.yml"

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_vite,node_main,node_app toneBlue
class node_catalog,node_account,node_purchase,node_orders,node_auth_views,node_shared_ui,node_protected_route toneAmber
class node_auth_context,node_cart_context,node_wishlist_context toneMint
class node_api,node_catalog_services,node_commerce_services,node_identity_service,node_backend toneRose
class node_deployment toneIndigo
```

## Components

### Client Runtime

- [Vite host](https://github.com/guywithnogirl/capybara_frontend/blob/main/vite.config.js): build runtime · Serves and builds the React SPA. · `vite.config.js`
- [React entry](https://github.com/guywithnogirl/capybara_frontend/blob/main/src/main.jsx): bootstrap · Mounts React and global styles. · `src/main.jsx`
- [App shell](https://github.com/guywithnogirl/capybara_frontend/blob/main/src/App.jsx): route composition · Composes public and authenticated application flows. · `src/App.jsx`

### Pages & UI

- [Catalog pages](https://github.com/guywithnogirl/capybara_frontend/blob/main/src/pages/Home.jsx): page feature · Home, shop, and product-detail browsing. · `src/pages/Home.jsx`
- [Account pages](https://github.com/guywithnogirl/capybara_frontend/blob/main/src/pages/Account.jsx): page feature · Account and address management views. · `src/pages/Account.jsx`
- [Purchase flow](https://github.com/guywithnogirl/capybara_frontend/blob/main/src/pages/Cart.jsx): page feature · Cart, checkout, payment, and order success views. · `src/pages/Cart.jsx`
- [Order views](https://github.com/guywithnogirl/capybara_frontend/blob/main/src/pages/OrderHistory.jsx): page feature · Order history and fulfillment detail views. · `src/pages/OrderHistory.jsx`
- [Auth views](https://github.com/guywithnogirl/capybara_frontend/blob/main/src/pages/Login.jsx): page feature · Login, registration, and password recovery. · `src/pages/Login.jsx`
- [Shared UI](https://github.com/guywithnogirl/capybara_frontend/blob/main/src/components/Navbar.jsx): component layer · Navigation, footer, loading, and reusable catalog components. · `src/components/Navbar.jsx`
- [Protected route](https://github.com/guywithnogirl/capybara_frontend/blob/main/src/components/ProtectedRoute.jsx): access control · Guards customer-only routes. · `src/components/ProtectedRoute.jsx`

### Shared State

- [Auth context](https://github.com/guywithnogirl/capybara_frontend/blob/main/src/context/AuthContext.jsx): React context · Holds current-user and session state. · `src/context/AuthContext.jsx`
- [Cart context](https://github.com/guywithnogirl/capybara_frontend/blob/main/src/context/CartContext.jsx): React context · Owns cart state and synchronization. · `src/context/CartContext.jsx`
- [Wishlist context](https://github.com/guywithnogirl/capybara_frontend/blob/main/src/context/WishlistContext.jsx): React context · Owns saved-product state. · `src/context/WishlistContext.jsx`

### API Integration

- [HTTP API client](https://github.com/guywithnogirl/capybara_frontend/blob/main/src/services/api.js): integration boundary · Common backend HTTP boundary. · `src/services/api.js`
- [Catalog services](https://github.com/guywithnogirl/capybara_frontend/blob/main/src/services/productService.js): service adapters · Products, categories, banners, and reviews. · `src/services/productService.js`
- [Commerce services](https://github.com/guywithnogirl/capybara_frontend/blob/main/src/services/cartService.js): service adapters · Cart, wishlist, orders, and addresses. · `src/services/cartService.js`
- [Auth service](https://github.com/guywithnogirl/capybara_frontend/blob/main/src/services/authService.js): service adapter · `src/services/authService.js`
- **Backend API**: external system · Backend implementation is outside this repository.

### Delivery

- [GitHub Pages deployment](https://github.com/guywithnogirl/capybara_frontend/blob/main/.github/workflows/deploy.yml): CI/CD workflow · Builds and deploys the static client. · `.github/workflows/deploy.yml`

## Connections

- Vite host → React entry: serves/builds
- React entry → App shell: mounts
- App shell → Catalog pages: routes to
- App shell → Auth views: routes to
- App shell → Protected route: guards routes through
- Protected route → Account pages: permits
- Protected route → Purchase flow: permits
- Protected route → Order views: permits
- Protected route → Auth context: checks
- App shell → Shared UI: uses
- Catalog pages → Catalog services: loads catalog
- Catalog pages → Cart context: adds items
- Catalog pages → Wishlist context: saves items
- Auth views → Auth service: authenticates via
- Auth service → HTTP API client: uses
- Auth context → Auth service: manages session via
- Purchase flow → Cart context: reads cart
- Purchase flow → Commerce services: creates order
- Order views → Commerce services: loads orders
- Account pages → Commerce services: manages addresses
- Cart context → Commerce services: synchronizes cart
- Wishlist context → Commerce services: synchronizes wishlist
- Catalog services → HTTP API client: uses
- Commerce services → HTTP API client: uses
- HTTP API client → Backend API: HTTP requests
- GitHub Pages deployment → Vite host: builds and deploys