Audiophile E-commerce Platform

A premium audio equipment e-commerce platform delivering a seamless shopping experience for high-fidelity audio enthusiasts.

Table of Contents

• Overview
• Features
• Tech Stack
• Prerequisites
• Installation
• Environment Variables
• Development
• Build & Deployment
• Project Structure
• Product Catalog
• Contributing
• License

Overview

Audiophile is a modern e-commerce platform specialized in premium audio equipment. Built with Next.js and TypeScript, it provides a fast, responsive, and intuitive shopping experience for customers seeking high-quality headphones, speakers, and earphones.

Key Highlights

• Server-side rendering for optimal performance
• Type-safe codebase with TypeScript
• Mobile-first responsive design
• Optimized image loading and lazy loading
• SEO-friendly architecture
• Accessible UI components

Features

Shopping Experience

• Product Catalog: Browse curated collections of premium audio equipment
• Category Navigation: Filter products by headphones, speakers, and earphones
• Product Details: Comprehensive product pages with high-resolution images, specifications, and features
• Image Gallery: Multiple product views with zoom functionality
• Related Products: Smart product recommendations

Cart & Checkout

• Shopping Cart: Real-time cart updates with quantity management
• Cart Persistence: Cart state preserved across sessions
• Checkout Flow: Streamlined multi-step checkout process
• Order Summary: Clear breakdown of costs including VAT and shipping
• Form Validation: Client-side validation for all user inputs

User Interface

• Responsive Design: Optimized layouts for mobile, tablet, and desktop
• Dark Mode Support: Seamless theme switching (if implemented)
• Smooth Animations: Polished micro-interactions and transitions
• Accessibility: WCAG 2.1 compliant components
• Performance: Lighthouse score 90+ across all metrics

Tech Stack

Core Framework

• Next.js 14+ - React framework with App Router
• TypeScript - Type safety and developer experience
• React 18+ - UI component library

Styling & UI

• Tailwind CSS - Utility-first CSS framework
• Lucide React - Beautiful & consistent icons
• CSS Modules - Component-scoped styling

State Management

• React Context API - Global state management
• React Hooks - Local component state
• LocalStorage - Cart persistence

Development Tools

• ESLint - Code linting and quality
• Prettier - Code formatting
• Git Hooks - Pre-commit checks

📦 Prerequisites

Ensure you have the following installed on your system:

• Node.js 18.17 or later
• npm 9+ or yarn 1.22+ or pnpm 8+
• Git for version control

Installation

1. Clone the Repository

git clone https://github.com/yourusername/audiophile-ecommerce.git
cd audiophile-ecommerce

2. Install Dependencies

# Using npm
npm install

# Using yarn
yarn install

# Using pnpm
pnpm install

# Using bun
bun install

3. Set Up Convex Backend

Initialize and configure Convex:

# Login to Convex (if not already logged in)
npx convex dev

# This will:
# - Create a Convex project (if needed)
# - Generate your Convex URL
# - Create/update .env.local with NEXT_PUBLIC_CONVEX_URL
# - Start the Convex development server

Note: If you already have a Convex project, the URL will be automatically added to your .env.local file. Otherwise, you'll need to add it manually:

NEXT_PUBLIC_CONVEX_URL=https://your-project.convex.cloud

4. Configure Environment Variables

Create a .env.local file in the root directory (if not already created by Convex):

cp .env.example .env.local

See Environment Variables section for required variables.

5. Run Development Server

In separate terminals, run:

# Terminal 1: Start Convex dev server (if not already running)
npx convex dev

# Terminal 2: Start Next.js dev server
npm run dev

Open http://localhost:3000 in your browser.

Environment Variables

Create a .env.local file with the following variables:

# App Configuration
NEXT_PUBLIC_APP_URL=http://localhost:3000
NEXT_PUBLIC_APP_NAME="Audiophile"

# Convex Backend (Required)
# Get your Convex URL by running 'npx convex dev' or from your Convex dashboard
NEXT_PUBLIC_CONVEX_URL=https://your-project.convex.cloud

# Clerk Authentication (if applicable)
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_xxxxx
CLERK_SECRET_KEY=sk_test_xxxxx

# API Configuration (if applicable)
NEXT_PUBLIC_API_URL=https://api.example.com
API_SECRET_KEY=your_secret_key_here

# Payment Gateway (if integrated)
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_xxxxx
STRIPE_SECRET_KEY=sk_test_xxxxx

# Analytics (optional)
NEXT_PUBLIC_GA_TRACKING_ID=G-XXXXXXXXXX

# Email Service (optional)
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=your_email@example.com
SMTP_PASSWORD=your_password

Environment Files

• .env.local - Local development (gitignored)
• .env.production - Production environment
• .env.example - Template file (committed to repo)

Important: Never commit .env.local or .env.production to version control.

Development

Available Scripts

# Start development server with hot reload
npm run dev

# Build for production
npm run build

# Start production server
npm run start

# Run linter
npm run lint

# Fix linting issues
npm run lint:fix

# Format code with Prettier
npm run format

# Type check
npm run type-check

# Run all checks (lint + type-check)
npm run check

Development Workflow

1. Create a feature branch:

   git checkout -b feature/your-feature-name

2. Make your changes following the code style

3. Test your changes locally

4. Commit with descriptive messages:

   git commit -m "feat: add product filtering functionality"

5. Push and create a pull request

Code Style Guidelines

• Used TypeScript for all new files
• Follow the existing folder structure
• Write descriptive component and function names
• Add JSDoc comments for complex functions
• Keep components small and focused (Single Responsibility Principle)
• Use Tailwind utility classes, avoid inline styles

Production Build

# Create optimized production build
npm run build

# Test production build locally
npm run start

Project Structure

audiophile-ecommerce/
├── app/                          # Next.js App Router
│   ├── (routes)/                 # Route groups
│   │   ├── headphones/          # Headphones category
│   │   ├── speakers/            # Speakers category
│   │   └── earphones/           # Earphones category
│   ├── product/[slug]/          # Dynamic product pages
│   ├── cart/                    # Shopping cart page
│   ├── checkout/                # Checkout page
│   ├── layout.tsx               # Root layout
│   ├── page.tsx                 # Home page
│   └── globals.css              # Global styles
├── components/                   # React components
│   ├── ui/                      # Reusable UI components
│   │   ├── Button.tsx
│   │   ├── Card.tsx
│   │   └── Input.tsx
│   ├── layout/                  # Layout components
│   │   ├── Header.tsx
│   │   ├── Footer.tsx
│   │   └── Navigation.tsx
│   ├── product/                 # Product-related components
│   │   ├── ProductCard.tsx
│   │   ├── ProductGrid.tsx
│   │   └── ProductDetail.tsx
│   └── cart/                    # Cart components
│       ├── CartItem.tsx
│       └── CartSummary.tsx
├── lib/                         # Utility functions
│   ├── utils.ts                # Helper functions
│   ├── constants.ts            # App constants
│   └── types.ts                # TypeScript types
├── hooks/                       # Custom React hooks
│   ├── useCart.ts
│   ├── useLocalStorage.ts
│   └── useMediaQuery.ts
├── context/                     # React Context providers
│   └── CartContext.tsx
├── data/                        # Static data
│   └── products.json           # Product catalog
├── public/                      # Static assets
│   ├── images/                 # Product images
│   ├── icons/                  # Icon files
│   └── favicon.ico
├── styles/                      # Additional styles
│   └── tailwind.config.ts      # Tailwind configuration
├── .env.example                 # Environment template
├── .eslintrc.json              # ESLint configuration
├── .gitignore                  # Git ignore rules
├── next.config.js              # Next.js configuration
├── package.json                # Dependencies
├── tsconfig.json               # TypeScript config
└── README.md                   # This file

License

This project is licensed under the MIT License