# bloodwraith8851/gocart architecture

> Architecture diagram of the GitHub repository bloodwraith8851/gocart, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bloodwraith8851/gocart
- Repository: https://github.com/bloodwraith8851/gocart

## Overview

##### Project Type and Purpose
- GoCart is a full-stack, multi-tenant e-commerce platform built on Next.js (App Router), React, Redux Toolkit, Clerk for authentication, Prisma ORM, and PostgreSQL.
- It serves three user roles: Public customers, Store owners (sellers), and Admins, each with its own UI subtree under `app/(public)`, `app/store`, and `app/admin`.

##### File Structure
- Top-level “app” directory is subdivided into:
- `(public)` – customer-facing pages and layout
- `store` – seller dashboard, product and order management
- `admin` – platform administration, store approval, coupons, analytics
- `layout.jsx` & `StoreProvider.js` – global wrappers (ClerkProvider, Redux Provider)
- `components/` holds reusable UI pieces, grouped further into `components/admin/` and `components/store/`.
- `lib/` contains Redux slice definitions (`features/*/…Slice.js`), `store.js` factory, and `prisma.js` for database client.
- `prisma/` folder holds the database schema.
- Middleware (`middleware.ts`) enforces route protection via Clerk.

##### README for Architectural Insights

a. Main Components
- Frontend
– Public Interface (pages under `app/(public)`)
– Store Owner Interface (`app/store/*`)
– Admin Interface (`app/admin/*`)
- Shared Frontend Services
– ClerkProvider for authentication
– Redux Store (Provider from `StoreProvider.js`) managing slices (cart, product, address, rating)
- Backend/API
– Next.js API routes and server actions in `app/api/*`
– Middleware for route protection
- Data Layer
– Prisma client (`lib/prisma.js`)
– PostgreSQL database (schema in `prisma/schema.prisma`)
- External Services
– Clerk (auth)
– Potential payment gateways (Stripe, COD)

b. Relationships and Interactions
- User action in a UI (Public/Store/Admin) → calls React component → uses Redux selectors or dispatches server actions via Next.js API routes.
- Redux dispatch → Next.js API route → Prisma client → Postgres → back to Redux → UI.
- ClerkProvider wraps the whole app to gate routes, with middleware enforcing protected paths for store/admin.
- StoreProvider instantiates the Redux store once and supplies it to all three interfaces.

c. Architectural Patterns and Principles
- Modular, zone-based UI: each user role has a dedicated sub-app.
- Centralized state management (Redux Toolkit) to decouple UI and data fetching.
- Provider pattern for auth (Clerk) and state (Redux) in `app/layout.jsx` → `StoreProvider.js`.
- Layered separation: Presentation (components/pages) → State (slices) → API/middleware → Persistence (Prisma/Postgres).
- Clear folder-per-feature organization for slices and components.

d. Key Technologies and Frameworks
- Next.js App Router for SSR, routing, and API routes.
- React + Redux Toolkit for UI and state.
- Clerk for authentication.
- Prisma ORM + PostgreSQL for data persistence.
- Tailwind CSS for styling.
- React Hot Toast, Recharts, Date-fns for notifications, charts, and date handling.

##### Detail without Overthinking
- Every major folder/module as its own component or sub-component.
- Three-tier user interface separation, centralized Redux, API boundary, ORM, and persistent store.
- Middleware’s role in protecting routes.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Auth Service
    ClerkService["Clerk Auth Service"]:::ext
    AuthProv["Global Auth Provider\napp/layout.jsx"]:::auth
    ClerkService -->|Auth| AuthProv

    %% Frontend Layer
    AuthProv -->|wraps| PublicUI
    AuthProv -->|wraps| StoreUI
    AuthProv -->|wraps| AdminUI

    PublicUI["Public Interface\napp/(public)"]:::frontend_public
    StoreUI["Store Owner Interface\napp/store"]:::frontend_store
    AdminUI["Admin Interface\napp/admin"]:::frontend_admin

    click PublicUI "https://github.com/bloodwraith8851/gocart/tree/main/app/(public)"
    click StoreUI "https://github.com/bloodwraith8851/gocart/tree/main/app/store"
    click AdminUI "https://github.com/bloodwraith8851/gocart/tree/main/app/admin"
    click AuthProv "https://github.com/bloodwraith8851/gocart/blob/main/app/layout.jsx"

    %% Shared UI Components and Assets
    SharedComp["Shared UI Components\ncomponents/"]:::static
    AdminComp["Admin-specific UI Components\ncomponents/admin/"]:::static
    StoreComp["Store-specific UI Components\ncomponents/store/"]:::static
    Styles["Global Styles\napp/globals.css"]:::static
    Static["Static Assets\nassets/assets.js"]:::static

    click SharedComp "https://github.com/bloodwraith8851/gocart/tree/main/components/"
    click AdminComp "https://github.com/bloodwraith8851/gocart/tree/main/components/admin/"
    click StoreComp "https://github.com/bloodwraith8851/gocart/tree/main/components/store/"
    click Styles "https://github.com/bloodwraith8851/gocart/blob/main/app/globals.css"
    click Static "https://github.com/bloodwraith8851/gocart/blob/main/assets/assets.js"

    PublicUI --> SharedComp
    StoreUI --> SharedComp
    StoreUI --> StoreComp
    AdminUI --> SharedComp
    AdminUI --> AdminComp

    %% Redux Store
    ReduxStore["Redux Store\nlib/store.js"]:::redux
    click ReduxStore "https://github.com/bloodwraith8851/gocart/blob/main/lib/store.js"

    PublicUI -->|"dispatch/useSelector"| ReduxStore
    StoreUI -->|"dispatch/useSelector"| ReduxStore
    AdminUI -->|"dispatch/useSelector"| ReduxStore

    %% Redux Slices
    Cart["Cart Slice\nlib/features/cart/cartSlice.js"]:::slice
    Addr["Address Slice\nlib/features/address/addressSlice.js"]:::slice
    Prod["Product Slice\nlib/features/product/productSlice.js"]:::slice
    Rating["Rating Slice\nlib/features/rating/ratingSlice.js"]:::slice

    click Cart "https://github.com/bloodwraith8851/gocart/blob/main/lib/features/cart/cartSlice.js"
    click Addr "https://github.com/bloodwraith8851/gocart/blob/main/lib/features/address/addressSlice.js"
    click Prod "https://github.com/bloodwraith8851/gocart/blob/main/lib/features/product/productSlice.js"
    click Rating "https://github.com/bloodwraith8851/gocart/blob/main/lib/features/rating/ratingSlice.js"

    ReduxStore --> Cart
    ReduxStore --> Addr
    ReduxStore --> Prod
    ReduxStore --> Rating

    %% Backend/API Layer
    subgraph "Backend/API Layer"
        APINode["Next.js API & Middleware"]:::backend_api
        APIRoutes["API Routes\napp/api"]:::backend_api
        Middleware["Middleware\nmiddleware.ts"]:::backend_api
    end

    click Middleware "https://github.com/bloodwraith8851/gocart/blob/main/middleware.ts"

    ReduxStore -->|API Calls| APIRoutes
    APIRoutes -->|protected by| Middleware

    %% ORM and Database
    Prisma["Prisma Client\nlib/prisma.js"]:::backend_api
    click Prisma "https://github.com/bloodwraith8851/gocart/blob/main/lib/prisma.js"
    Schema["DB Schema\nprisma/schema.prisma"]:::db
    click Schema "https://github.com/bloodwraith8851/gocart/blob/main/prisma/schema.prisma"
    DB["PostgreSQL DB"]:::db

    APIRoutes --> Prisma
    Middleware --> Prisma
    Prisma --> Schema
    Schema --> DB

    %% Styles
    classDef frontend_public fill:#add8e6,stroke:#0000ff
    classDef frontend_store fill:#90ee90,stroke:#008000
    classDef frontend_admin fill:#dda0dd,stroke:#800080
    classDef ext fill:#e0ffff,stroke:#20b2aa,stroke-width:2px
    classDef auth fill:#f0f8ff,stroke:#4682b4
    classDef redux fill:#ffd1dc,stroke:#d6336c
    classDef slice fill:#ffe5b4,stroke:#ffa500
    classDef backend_api fill:#fafad2,stroke:#ffd700
    classDef db fill:#fff5ee,stroke:#cd5c5c
    classDef static fill:#d3d3d3,stroke:#696969
```
