From b7cb4136058504ca533fb1a2d92198638aabf0c2 Mon Sep 17 00:00:00 2001
From: Timo Knuth <knuth.timo@gmail.com>
Date: Wed, 14 Jan 2026 19:45:10 +0100
Subject: [PATCH] readme

---
 Pottery-website/README.md | 124 ++++++++++++++++++++++++++++++++++----
 1 file changed, 111 insertions(+), 13 deletions(-)

diff --git a/Pottery-website/README.md b/Pottery-website/README.md
index 3a78e0c..beb828f 100644
--- a/Pottery-website/README.md
+++ b/Pottery-website/README.md
@@ -1,20 +1,118 @@
-<div align="center">
-<img width="1200" height="475" alt="GHBanner" src="https://github.com/user-attachments/assets/0aa67016-6eaf-458a-adb2-6e31a0763ed6" />
-</div>
+# HOTSCHPOTSH — Handmade Pottery Atelier
 
-# Run and deploy your AI Studio app
+Welcome to the official repository for **HOTSCHPOTSH**, 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.
 
-This contains everything you need to run your app locally.
+---
 
-View your app in AI Studio: https://ai.studio/apps/drive/1xMGYSZE5oFy0eXRMfs741pq-jMBBDS7Y
+## 🏛️ Project Architecture
 
-## Run Locally
+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.
 
-**Prerequisites:**  Node.js
+---
 
+## ⚡ Main Features
 
-1. Install dependencies:
-   `npm install`
-2. Set the `GEMINI_API_KEY` in [.env.local](.env.local) to your Gemini API key
-3. Run the app:
-   `npm run dev`
+- **🛒 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.**