# KNUTH Ceramics — Handmade Pottery Atelier

Welcome to the official repository for **KNUTH Ceramics**, a premium handmade pottery e-commerce platform and editorial site. This project features a React-based frontend, a Node.js/Express backend, and a PostgreSQL database for full content and order management.

---

## 🏛️ Project Architecture

The application is split into two main parts:
- **Frontend**: Built with React, Vite, Framer Motion (animations), and Vanilla CSS.
- **Backend**: Node.js/Express server providing a RESTful API for products, articles, and orders.
- **Database**: PostgreSQL with custom schema and migration scripts.

---

## ⚡ Main Features

- **🛒 Shopping Experience**: Persistent shopping bag (localStorage), quantity management, and a dedicated checkout flow.
- **💳 Mock Payment Integration**: A simulated payment system that validates the checkout process and records orders without requiring live Stripe keys.
- **📰 Editorial Section**: A "Journal" with rich storytelling, featuring articles with dynamic sections and featured post placement.
- **🛠️ Admin Dashboard**: A secure management interface to:
  - Create, update, and delete products (images, prices, descriptions).
  - Manage articles (rich content editor, featuring toggle).
  - **Fulfill Orders**: View customer details and update shipping status (Pending → Shipped → Delivered).

---

## 🚀 Getting Started

### Prerequisites
- **Node.js** (v18+ recommended)
- **PostgreSQL** instance (Local or Remote)
- **npm** or **yarn**

### 1. Database Setup
1. Create a new PostgreSQL database (e.g., `pottery_db`).
2. Navigate to the `server` directory:
   ```bash
   cd server
   ```
3. Initialize the schema:
   ```bash
   # Option A: Run scripts manually using schema.sql
   # Option B: Run the setup script (requires DB credentials in .env)
   node db_setup.js
   ```
4. Run migrations for the latest features (like the `orders` table):
   ```bash
   node migrate.js
   ```

### 2. Backend Configuration
1. In the `server` directory, create a `.env` file based on the following template:
   ```env
   PORT=5000
   DB_USER=your_username
   DB_HOST=localhost
   DB_NAME=pottery_db
   DB_PASSWORD=your_password
   DB_PORT=5432
   ```
2. Install dependencies:
   ```bash
   npm install
   ```
3. Start the server:
   ```bash
   # Development (with nodemon)
   npm run dev

   # Production
   npm start
   ```

### 3. Frontend Configuration
1. Return to the project root:
   ```bash
   cd ..
   ```
2. Install dependencies:
   ```bash
   npm install
   ```
3. Start the development server:
   ```bash
   npm run dev
   ```
4. Open your browser at `http://localhost:5173`.

---

## 🛡️ Admin Dashboard Usage

Access the dashboard by navigating to `/admin`.
- **Products**: Manage your shop inventory.
- **Editorial**: Write and manage blog posts.
- **Orders**: Monitor incoming sales. Use the "Visibility" icon to view customer shipment details and update their fulfillment status.

---

## ⚠️ Important Considerations

- **Storage Limits**: The shopping cart uses `localStorage`. To avoid the `QuotaExceededError`, only item IDs and quantities are stored. The application automatically hydrates this data from the backend.
- **Large Images**: When uploading high-resolution images via the Admin UI, ensure they are optimized. The system supports Base64 encoding for simplicity, but large files may impact performance.
- **Mock Checkout**: The "Mock Payment" page is designed for testing. In a production environment, this should be replaced with a live Stripe `CheckoutSession` or equivalent provider.

---

## 📦 Directory Structure

- `/components`: Reusable UI elements (Cart, Header, Footer, etc.).
- `/pages`: Main view routes (Home, Collections, Admin, Checkout).
- `/server`: Node Express backend and database logic.
- `/src/context`: Global state management via `StoreContext`.

---

**Crafted with care by Antigravity.**
