🎛️ OpenCommerce Admin Panel

OpenCommerce Admin Panel is the open source staff console for OpenCommerce — a full-featured eCommerce platform. Built with Next.js, React, and Tailwind CSS, it gives warehouse admins, marketers, and support agents a role-aware workspace for orders, catalog, customers, marketing, finance, and platform settings.

Pair it with the OpenCommerce backend (Node.js + Express + MongoDB) and the storefront for a complete open source commerce stack.

backend repo: https://github.com/TheCasperSolangi/ecommerce_backend
frontend (storefront) repo: https://github.com/TheCasperSolangi/ecommerce_frontend

---

✨ Features

• 🔐 Staff-only auth — Login for admin, marketing, and customer_support (customers are redirected to the storefront)
• 🧭 Role-aware sidebar — Navigation filtered by role so each user only sees tools they can use
• 📊 Dashboard — Warehouse-scoped stats, recent activity, and charts
• 📦 Orders — Status cards, search, detail dialog, status transitions, and refunds
• 🛍️ Products — Catalog list with search, create / edit / soft-delete, brands & categories, image upload to storage
• 👥 Team — Invite staff, assign roles & warehouses, lock / unlock / remove accounts
• 🧍 Customers — Browse end users; lock or unlock accounts (admin + support)
• 🎫 Tickets — Triage support tickets (status + team notes; notifies the customer)
• 🏷️ Coupons — Full coupon CRUD with eligibility, expiry, usage limits, and active toggle
• 🖼️ Banners — Sliders, pop-ups, app & header banners with upload and storefront visibility toggle
• 📣 Marketing — Create campaigns (Email / WhatsApp / Push), then broadcast with delivery stats
• 🏪 Vendors — Maintain vendor records for expense tagging
• 💰 Finance — Income / expense / net summary and ledger with manual entries
• ⚙️ Settings — Profile & password for all staff; platform branding and warehouses for admins

---

🧰 Tech Stack

Layer	Technology
Framework	Next.js (App Router)
UI	React, Lucide React, React Icons, Radix UI primitives
Styling	Tailwind CSS
Charts	Recharts
Auth	JWT (Bearer) in cookies (token / authToken)
API client	Fetch helpers in src/lib/ via NEXT_PUBLIC_API_URL

---

👤 Roles & access

Module	Admin	Marketing	Customer support
Dashboard	✅	✅	✅
Orders	✅	—	✅*
Products	✅	✅ (view-oriented; mutate is admin)	—
Banners	✅	✅	—
Marketing	✅	✅	—
Coupons	✅	✅	—
Team	✅	—	—
Customers	✅	—	✅
Tickets	✅	—	✅
Vendors	✅	—	—
Finance	✅	—	—
Settings	✅ (all tabs)	✅ (profile)	✅ (profile)

*Order management APIs are warehouse-scoped and typically require admin privileges on the backend; support may see the nav depending on your API policy.

Staff create flows (Team → Add member) can also create rider accounts for delivery operations; riders do not use this panel.

---

📋 Prerequisites

• Node.js 18+ and npm
• A running OpenCommerce backend (default API: http://localhost:6464)
• A running storage / upload server for product & banner images (default: http://localhost:4755)
• At least one staff user (admin / marketing / customer_support) in the backend

---

🚀 Getting Started

1. Clone & install

git clone <your-admin-panel-repo-url>.git
cd admin_panel
npm install

2. Environment variables

Create a .env (or .env.local) in the project root:

# OpenCommerce backend API (must match backend PORT, default 6464)
NEXT_PUBLIC_API_URL=http://localhost:6464/api

# Image storage server
NEXT_PUBLIC_STORAGE_URL=http://localhost:4755

3. Start the backend & storage

Make sure the API is up on port 6464 and the storage server on 4755 before signing in or uploading images.

4. Run the admin panel

npm run dev

Open http://localhost:3000 (or the port Next.js prints). If the storefront already uses 3000, start the panel on another port:

npx next dev -p 3001

5. Sign in

Go to /auth/login with a staff email and password. Only management roles are accepted.

6. Production build

npm run build
npm start

---

📁 Project Structure

admin_panel/
├── src/
│   ├── app/
│   │   ├── auth/login/           # Staff login
│   │   └── dashboard/            # Authenticated shell
│   │       ├── page.js           # Dashboard
│   │       ├── orders/
│   │       ├── products/         # List + new + [id]/edit
│   │       ├── banners/
│   │       ├── marketing/
│   │       ├── coupons/
│   │       ├── team/
│   │       ├── customers/
│   │       ├── tickets/
│   │       ├── vendors/
│   │       ├── finance/
│   │       └── settings/
│   ├── components/
│   │   ├── dashboard/            # Sidebar, shell, charts
│   │   ├── products/             # ProductForm, brand/category dialogs
│   │   ├── team/                 # Create staff dialog
│   │   └── ui/                   # Shared UI primitives
│   ├── context/                  # AuthContext
│   ├── lib/                      # API helpers (orders, products, users, …)
│   └── hooks/ · i18n/
├── public/
├── .env                          # NEXT_PUBLIC_API_URL, NEXT_PUBLIC_STORAGE_URL
└── package.json

---

🗺️ Main Routes

Route	Description
/auth/login	Staff sign-in
/dashboard	Overview & charts
/dashboard/orders	Orders management
/dashboard/products	Product catalog
/dashboard/products/new	Create product
/dashboard/products/[id]/edit	Edit product
/dashboard/banners	Banner management
/dashboard/marketing	Marketing campaigns
/dashboard/coupons	Coupon management
/dashboard/team	Team / staff management
/dashboard/customers	Customer accounts
/dashboard/tickets	Support tickets
/dashboard/vendors	Vendors
/dashboard/finance	Finance ledger
/dashboard/settings	Profile, platform, warehouses

---

🔐 Auth & session

• Access token is stored in cookies (token / authToken) with role and optional warehouse_code
• Authenticated requests send Authorization: Bearer <token> via src/lib/api.js
• AuthContext loads GET /api/auth/me on boot and blocks non-management roles
• Account locks (suspended status or failed-login lock) are enforced by the backend

---

🖼️ Images in development

Product, brand, banner, and marketing image uploads go to:

POST {NEXT_PUBLIC_STORAGE_URL}/api/uploads

Ensure that host is reachable from the browser during local development.

---

🤝 Contributing

Contributions are welcome! A good starting path:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/your-feature)
3. Make focused changes with clear commits
4. Open a pull request describing the why and how to test

Please keep PRs scoped, match existing patterns in src/lib/ and dashboard pages, and avoid unrelated refactors.

---

🐛 Reporting issues

If you find a bug or have a feature request, open an issue with:

• Steps to reproduce
• Expected vs actual behavior
• Browser / Node versions
• Staff role used (admin / marketing / customer_support)
• Whether the backend API and storage server were running and reachable

---

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

---

❤️ Acknowledgments

Built as the companion admin console to OpenCommerce, an open source eCommerce platform for developers who want full control over their commerce stack.