Nebi Store - E-commerce Application

A full-stack e-commerce application built with a Django REST Framework backend and a Next.js/TypeScript frontend. Features a modern, responsive design with comprehensive functionality for online shopping.

🚀 Features

Backend (Django REST Framework)

• RESTful API: Complete CRUD operations for products, orders, customers, and more
• Authentication & Authorization: JWT-based authentication with role-based access control
• Database: PostgreSQL with proper migrations and data models
• Admin Dashboard: Analytics and management interface for store operations
• Payment Integration: Chapa payment gateway integration
• Product Management: Categories, collections, images, reviews, and discounts
• Order Processing: Complete order lifecycle with status tracking
• Customer Management: Membership system with Bronze/Silver/Gold tiers
• Analytics: Admin dashboard with sales and performance metrics
• Comprehensive Testing: Unit, integration, and end-to-end tests for all critical functionality

Frontend (Next.js/TypeScript)

• Modern Tech Stack: Next.js 15 + React 19 + TypeScript + Tailwind CSS
• Server Components: Homepage uses Next.js Server Components for optimal performance
• Real-time Product Data: Hero section, featured, latest, and trending products from backend APIs
• Responsive Design: Mobile-first approach with seamless desktop experience
• Product Management: Browse, search, filter, and view detailed product pages
• Shopping Cart: Add/remove items, update quantities, persistent cart storage with backend sync
• Checkout Process: Complete order flow with form validation and payment integration
• Real API Integration: Connected to Django backend (no mock data, all sections use live endpoints)
• State Management: Zustand with persistence for cart and auth state
• Accessibility: WCAG compliant with keyboard navigation and screen reader support
• Performance: Server-side data fetching, Suspense boundaries, lazy loading, optimized images

🎨 Design System

Color Palette

• Primary Blue: #BEE9FF - Page background
• Gold Accent: #D4AF37 - CTAs and highlights
• Cream: #FFF6E0 - Secondary surfaces and hover states
• Text: #1F2937 - Primary text color
• Muted: #6B7280 - Secondary text and helpers

Typography

• Font Family: Inter, system-ui, -apple-system, "Segoe UI", Roboto, Arial
• Focus States: Custom glow effect using CSS variables
• Shadows: Subtle elevation with 0 6px 18px rgba(2,6,23,0.06)

📁 Project Structure

ecommerce-app/
├── backend/                    # Django REST Framework backend
│   ├── storefront/            # Django project settings & URL config
│   ├── store/                 # Main e-commerce app (products, orders, carts, customers)
│   ├── core/                  # Custom user model & Djoser serializers
│   ├── analytics/             # Admin analytics views (daily sales, collection breakdown)
│   ├── likes/                 # Product likes functionality
│   ├── tags/                  # Product tagging system
│   ├── playground/            # Development utilities
│   └── manage.py              # Django management script
├── frontend/                  # Next.js frontend (App Router)
│   ├── app/                  # Route segments and pages
│   │   ├── admin/            # Admin console (staff only)
│   │   │   ├── dashboard/    # Overview + live stats
│   │   │   ├── products/     # Product CRUD
│   │   │   ├── collections/  # Collection CRUD
│   │   │   ├── orders/       # Order management + status updates
│   │   │   ├── customers/    # Customer list + membership management
│   │   │   ├── memberships/  # Membership plan CRUD
│   │   │   ├── banners/      # Promo banner CRUD
│   │   │   ├── payment-methods/ # Payment method config
│   │   │   └── analytics/    # Live analytics charts
│   │   ├── products/         # Product catalog & detail pages
│   │   ├── cart/             # Shopping cart
│   │   ├── checkout/         # Checkout flow
│   │   ├── orders/           # User order history
│   │   ├── profile/          # User profile + delete account
│   │   ├── login/            # Login (email + password)
│   │   ├── register/         # Registration with strict validation
│   │   └── forgot-password/  # Password reset
│   ├── components/           # Reusable UI components
│   │   └── admin/            # AdminShell sidebar layout
│   ├── lib/                  # API client, helpers, state, types, validation
│   └── public/               # Static assets
└── .env.example              # Environment variables template

🛠 Installation & Setup

Prerequisites

• Python 3.11+
• Node.js 18+
• PostgreSQL 15+ (running locally on port 5433)

Backend Setup

1. Install Python dependencies

cd backend
pipenv install

2. Configure environment variables

cp .env.example .env
# Edit .env with your PostgreSQL credentials

3. Create and migrate database

pipenv run python manage.py migrate

4. Create superuser (Django prompts for email as the login identifier, plus username and password)

pipenv run python manage.py createsuperuser

Mark the account as staff in Django admin (/django-admin/) or set is_staff=True if you need the Next.js admin UI at /admin/dashboard (see below).

5. Run tests

pipenv run pytest
# This will run all unit, integration, and end-to-end tests

6. Start development server

pipenv run python manage.py runserver
# Server will run on http://127.0.0.1:8000

Frontend Setup

1. Install Node.js dependencies

cd frontend
npm install

2. Configure environment variables

cp .env.example .env
# Edit .env with your API configuration

3. Start development server

npm run dev
# Server will run on http://localhost:3000

📦 Frontend Deployment (Vercel)

Prerequisites

• GitHub repository synced with the latest code.
• Vercel account (free tier works fine).

Steps

1. Push latest changes

   git add .
   git commit -m "Prepare frontend for Vercel deployment"
   git push origin main
   

2. Import project to Vercel

   • Go to https://vercel.com/dashboard.

   • Click New Project → Import Git Repository → select your GitHub repo.

   • Vercel auto-detects a Next.js project.

     • Set the Root Directory to frontend so Vercel builds the Next.js app in the correct folder.

3. Configure Environment Variables

   • In the Vercel dashboard, navigate to Project Settings → Environment Variables.
   • Add NEXT_PUBLIC_API_URL pointing to your production backend API (e.g., https://api.nebistore.com).
   • Add NEXT_PUBLIC_API_URL pointing to your production backend API (e.g., https://api.nebistore.com/api/v1).

4. Deploy

   • Click Deploy. Vercel will run npm install and npm run build.
   • After a successful build, your site will be live at https://<project-name>.vercel.app.

Post‑Deployment Checklist

• Verify homepage loads with real product data.
• Test cart persistence, login, checkout flow.
• Ensure all API calls hit the production backend (check network requests).
• Confirm responsive design on mobile devices.

For more detailed instructions, see frontend/VERCEL_DEPLOYMENT.md.

Database Setup

The application uses PostgreSQL running locally on port 5433. Ensure PostgreSQL is installed and running before starting the application.

🧩 Troubleshooting

• store_promobanner table does not exist
  If you see errors like relation "store_promobanner" does not exist when hitting /store/promotions/, run:

  cd backend
  pipenv run python manage.py makemigrations store
  pipenv run python manage.py migrate
  

  Then restart the Django development server.

Storefront conventions

• Currency: Prices in the UI are formatted as Ethiopian Birr (ETB). Cart shipping is a simple ETB rule (see frontend/lib/shipping.ts).
• Login: Users sign in with email + password (User.USERNAME_FIELD = 'email' on the backend).
• Phone format: The app enforces Ethiopian mobile format +251XXXXXXXXX (13 characters, starting with +2519 or +2517) via frontend/lib/validation.ts. This is validated client-side before form submission.
• Admin UI (Next.js): After logging in, staff users (is_staff=True) get an Admin Console link in the account menu and can open /admin/dashboard. Non-staff users are redirected away by middleware.

📱 Features Overview

Product Catalog

• Grid Layout: Responsive 1→2→3→4 column grid
• Product Cards: Fixed-height images, sale badges, price formatting
• Search & Filter: By category, sale status, price sorting
• Pagination: Efficient loading of large product sets
• Product Reviews: Customer reviews with ratings and comments

Shopping Cart

• Persistent storage: Cart state in localStorage (Zustand) with line totals from unit/sale prices
• Quantity controls: Per-line quantity with totals and a cart count badge in the navbar
• Checkout: Creates a server cart, posts line items, then creates an order via the REST API

Checkout Process

• Form Validation: Client-side validation with error messaging
• Payment Methods: Chapa payment gateway integration
• Billing Address: Complete address collection
• Order Confirmation: Success page with order ID

User Management

• Authentication: Login, registration with strict field validation, password reset
• Form Validation: Inline field-level errors on blur and submit for all registration fields
• Phone Validation: Ethiopian +251 format enforced (+2519XXXXXXXX or +2517XXXXXXXX)
• Role-Based Access: Admin (is_staff=True), customer roles with different permissions
• Membership System: Bronze (B), Silver (S), Gold (G) membership tiers with discounts
  • Auto-updates based on total spend: >1000 ETB → Gold, >500 ETB → Silver
• Profile Management: User profile, phone number, date of birth, address management
• Delete Account: Secure account deletion with password confirmation and type-to-confirm safeguard (DELETE /auth/users/me/)

Admin Dashboard (/admin/dashboard)

All pages require is_staff=True. Accessible via the Admin Console link after login.

Page	Path	API Endpoints
Overview	/admin/dashboard	GET /store/admin-stats/, GET /store/orders/
Products	/admin/products	Full CRUD /store/products/
Collections	/admin/collections	Full CRUD /store/collections/
Orders	/admin/orders	GET /store/orders/, PATCH /store/orders/{id}/
Customers	/admin/customers	GET /store/customers/, PATCH /store/customers/{id}/
Memberships	/admin/memberships	Full CRUD /store/memberships/
Promo Banners	/admin/banners	Full CRUD /store/promotions/
Payment Methods	/admin/payment-methods	GET/PATCH /store/payment-methods/
Analytics	/admin/analytics	GET /store/admin-stats/, GET /analytics/data/

Admin features include:

• Analytics: Live stats (sales, orders, products, customers) + daily sales bar chart + top-collections chart
• Product Management: Create/edit (with discount fields), delete (protected if order-referenced), image preview
• Order Management: Paginated list with status filter, inline Pending→Complete→Failed status updates
• Customer Management: List all customers with membership badges, inline membership level changes
• Membership System: Full CRUD for Bronze/Silver/Gold plans with discount % and perks
• Promo Banners: Create/edit banners with zone, animation, scheduling, click/impression tracking
• Payment Methods: Enable/disable/coming-soon toggles for Chapa, Telebirr, etc.

🔌 Backend API Reference