gn33-shop

An e-commerce platform for a small handmade (knitted and crocheted) goods business. It serves a public, server-rendered storefront for shoppers and a back office for the maker and staff. The brand is gn33, and the public origin is shop.gn33.eu.

Overview

The project is two independent applications, each in its own git repository. It is not a monorepo.

App	Path	Stack
Backend	gn33-shop-app	Java 26, Spring Boot 4.1, Maven, PostgreSQL, Flyway
Frontend	gn33-shop-spa	React 19, TypeScript, TanStack Start (SSR) on Vite, pnpm
Deployment	gn33-shop-deploy	Docker Compose, Caddy, fronted by Nginx Proxy Manager on TrueNAS

The project was forked in July 2026 from a fitness-studio booking platform, to reuse its user, authentication and security stack. The two codebases are intentionally separate and expected to diverge.

Features

Storefront (public)

• Server-rendered catalogue with categories, search and a data-driven filter rail (colour, size, material, price range).
• Product pages with variants, per-variant delivery estimates and compliance disclosures.
• Featured products, a shop landing page and a member home dashboard.
• Anonymous cart, wishlist and a two-step checkout (Delivery, then Review) that works for guests and account holders.
• Order history and order detail pages for members, with a free-cancellation window.

Back office (staff)

• Catalogue admin: create and edit products with an aggregate save, draft preview, duplicate, image upload with drag-to-reorder, and category CRUD.
• Library: managed yarns, sizes and materials, shared across products so filters and labelling stay consistent.
• Order board: a five-column pipeline (New, In the making, Ready, Shipped, Cancelled) plus an "Awaiting payment" strip, manual mark-as-paid, and due-date and overdue indicators.
• Users: stat cards, order counts and lifetime value, and an Active, Blocked or Unverified badge.
• Settings: per-category making lead time and seasonal batch CRUD.
• CSV import: stock levels by SKU.

Accounts and security

• Registration with PIN verification, login with optional 2FA, password reset, and Google and Facebook sign-in.
• Email verification for accounts created at checkout.
• Role-based access (member, manager, admin).
• Rate limiting, brute-force protection, and legal-consent gating (terms and GDPR).
• All findings from the 2026-09-15 security audit have been fixed.

Internationalisation

• Five locales are maintained in full parity: English, Romanian, German, Spanish and French.
• Parity is enforced by tests on both apps.
• Transactional emails are rendered from Thymeleaf templates with branding taken from configuration.

Architecture notes

• The SPA server-renders the storefront and the whole authenticated subtree.
• Server-side query state is dehydrated to the client, so pages do not refetch on hydration.
• The server session is keyed per request, so no visitor state leaks between requests.
• The SPA's production image runs on Node through server.mjs.
• The backend is layered (controller, service, repository) with Flyway migrations (currently up to V13).
• Ownership checks live in the service layer, and admin DTOs never reach customer-reachable endpoints.
• Yarn, size and material are first-class entities, but order lines keep plain-string snapshots so renames never rewrite order history.
• Stock updates use pessimistic row locks, which is proven by a two-thread integration test.
• Backend test suite is about 573 tests, using Mockito and Testcontainers.
• The frontend has typecheck, lint, Vitest and build gates.

Status

• All eight slices of the shop-surfaces plan are complete, along with catalogue admin, catalogue filters and the security-audit fixes.
• There is no payment step yet, so orders land in PENDING_PAYMENT and staff mark them as paid manually.
• Netopia payments stay in mock mode until the Phase 3 decision in ROADMAP.md.
• Shipments and stock-movement records do not exist yet.
• Placeholder business data (contact info, legal entity details, real shipping rate) still needs the owner's real values.
• Not yet built: global nav search, a Collections nav item, "Keep me signed in", and import history.