145 lines
4.8 KiB
Markdown
145 lines
4.8 KiB
Markdown
# 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.**
|
|
|
|
## 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:
|
|
|
|
```bash
|
|
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.
|