hotschpotsh/Pottery-website

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:

   cd server
   

3. Initialize the schema:

   # 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):

   node migrate.js
   

2. Backend Configuration

1. In the server directory, create a .env file based on the following template:

   PORT=5000
   DB_USER=your_username
   DB_HOST=localhost
   DB_NAME=pottery_db
   DB_PASSWORD=your_password
   DB_PORT=5432
   

2. Install dependencies:

   npm install
   

3. Start the server:

   # Development (with nodemon)
   npm run dev
   
   # Production
   npm start
   

3. Frontend Configuration

1. Return to the project root:

   cd ..
   

2. Install dependencies:

   npm install
   

3. Start the development server:

   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.

Docker Deployment with Caddy

For a self-hosted deployment, this repository now includes:

• Dockerfile.frontend: Builds the Vite frontend and serves it with Caddy.
• server/Dockerfile: Runs the Node/Express API.
• docker-compose.yml: Starts Caddy, the API, and PostgreSQL together.
• server/init.sql: Initializes the database schema on first startup.

Quick Start

1. Copy .env.example to .env.
2. Set SITE_HOST to your domain name.
3. Set a strong POSTGRES_PASSWORD.
4. Start the stack:

docker compose up -d --build

Notes

• Caddy terminates TLS automatically when SITE_HOST points to a public domain with correct DNS.
• The frontend uses /api in production, and Caddy proxies that path to the backend container.
• PostgreSQL data is stored in the postgres_data Docker volume.