⌨️ KeyForge - Artisan Mechanical Keyboard Shop

Crafting unique typing experiences. Artisan keycaps, premium switches, and ergonomic accessories designed in Poland.

KeyForge is a modern, full-stack e-commerce application. It provides a seamless shopping experience for mechanical keyboard enthusiasts and a robust Content Management System (CMS) for store administrators.

Built with a focus on type safety, performance, and containerization.

---

🚀 Tech Stack

Frontend

Backend & DevOps

---

🌟 Key Features

🛒 Customer Storefront

• Product Discovery: Filterable catalog with categories, sorting, and search functionality.
• Variant System: Support for complex product variations (e.g., switch types, keycap sets) with shared inventory tracking.
• Cart Management: Persistent shopping cart powered by localStorage and React Context.
• Flexible Checkout:
  • Guest Checkout: Seamless purchase flow without registration (email required).
  • Member Checkout: Fast-track checkout using saved addresses for logged-in users.
• User Hub: Order history tracking and address book management.

🛡️ Admin Dashboard

A secure, role-based panel (ADMIN role required) to manage the business.

• Inventory Management:
  • Create, update, and archive products.
  • Manage images and technical specifications.
  • Soft-delete mechanism to preserve historical order data.
• Order Processing:
  • Centralized list of all orders (Guest & Registered).
  • Status workflow management (Pending → Shipped → Delivered).
  • Quick-View Modal: Instant access to shipping details and order contents without leaving the list.
• User Management:
  • Customer database overview.
  • Order frequency analytics per user.
  • Security protocols preventing self-deletion of admin accounts.

---

📸 Gallery

The project includes over 50 high-fidelity screens covering the entire user and admin journey.

👉 Click here to view the Full Project Gallery (GALLERY.md)

---

⚙️ Local Development Setup

Prerequisites: Node.js (v18+) and Docker Desktop.

1. Clone Repository

git clone [https://github.com/your-username/keyforge.git](https://github.com/your-username/keyforge.git)
cd keyforge

2. Start the Database (Docker)

The project includes a docker-compose.yml file to spin up the PostgreSQL database automatically.

# Start the database container in detached mode
docker-compose up -d

This will start PostgreSQL on port 5433 to avoid conflicts with local installations.

3. Backend Configuration (/server)

cd server
npm install

Create a .env file in the server directory. Note: Ensure the port matches the Docker configuration (5433).

PORT=3000
NODE_ENV=development
# Connecting to Docker container on port 5433
DATABASE_URL="postgresql://admin:adminpassword@localhost:5433/keyforge?schema=public"
JWT_SECRET="your-development-secret-key"

Initialize the database schema:

npx prisma generate  # Generate Prisma Client
npx prisma db push   # Sync schema with the Docker database
npm run dev          # Start API server on port 3000

4. Frontend Configuration (/client)

Open a new terminal terminal:

cd client
npm install
npm run dev

The application will be available at http://localhost:5173.

---

🗄️ Database Schema

The application uses a relational model optimized for e-commerce:

• User: Handles authentication, roles, and profile data.
• SavedAddress: One-to-many relation for user shipping addresses.
• Product & ProductVariant: Hierarchical structure allowing multiple stock keeping units (SKUs) under one product listing.
• Order & OrderItem: Snapshots of pricing and variant data at the moment of purchase to ensure historical accuracy.

---

🤝 Author

Wiktor Trybus

• GitHub: @Veexeq

---

This project was created as a final assignment for the Introduction to Web Applications course at the Faculty of Computer Science, AGH University of Science and Technology.