mycopunk-swag-store/CLAUDE.md

Mycopunk Swag Store - AI Assistant Context

Project Overview

E-commerce platform for mycopunk merchandise (stickers, shirts, prints) with Stripe payments and print-on-demand fulfillment via Printful and Prodigi.

Architecture

• Frontend: Next.js 15 App Router, shadcn/ui, Tailwind CSS
• Backend: FastAPI, SQLAlchemy, Alembic
• Database: PostgreSQL
• Payments: Stripe Checkout (redirect flow)
• Fulfillment: Printful (apparel), Prodigi (stickers/prints)
• Deployment: Docker on Netcup RS 8000, Traefik routing

Key Directories

Directory	Purpose
backend/app/api/	FastAPI route handlers
backend/app/models/	SQLAlchemy ORM models
backend/app/schemas/	Pydantic request/response schemas
backend/app/services/	Business logic (stripe, pod, orders)
backend/app/pod/	POD provider clients (from mycopunk-swag)
frontend/app/	Next.js App Router pages
frontend/components/	React components

Design Source

Designs are read from the mycopunk-swag repo at runtime:

• Local: /home/jeffe/Github/mycopunk-swag/designs/
• Docker: Volume mounted from /opt/mycopunk-swag/designs

Each design has a metadata.yaml with name, description, products, variants, and pricing.

API Endpoints

Public

• GET /api/designs - List active designs
• GET /api/designs/{slug} - Get design details
• GET /api/designs/{slug}/image - Serve design image
• GET /api/products - List products with variants
• POST /api/cart - Create cart
• GET/POST/DELETE /api/cart/{id}/items - Cart operations
• POST /api/checkout/session - Create Stripe checkout
• GET /api/orders/{id} - Order status (requires email)

Webhooks

• POST /api/webhooks/stripe - Stripe payment events
• POST /api/webhooks/prodigi - Prodigi fulfillment updates
• POST /api/webhooks/printful - Printful fulfillment updates

Admin (JWT required)

• POST /api/admin/auth/login - Admin login
• GET /api/admin/orders - List orders
• GET /api/admin/analytics/* - Sales metrics

Order Flow

1. Customer adds items to cart (cart_id in localStorage)
2. Checkout creates Stripe session, redirects to Stripe
3. Stripe webhook fires on payment success
4. Backend creates order, submits to POD provider
5. POD webhook updates order status
6. Customer receives email notifications

Common Tasks

Run locally

docker compose up -d

Run migrations

cd backend
alembic upgrade head

Add a new API endpoint

1. Create route in backend/app/api/
2. Add Pydantic schemas in backend/app/schemas/
3. Register router in backend/app/main.py

Add a new component

cd frontend
npx shadcn@latest add button  # or other component

Environment Variables

See .env.example for all required variables.

Testing

# Backend
cd backend
pytest

# Frontend
cd frontend
pnpm test

Deployment

Push to Gitea triggers webhook → auto-deploy on Netcup.

Manual deploy:

ssh netcup "cd /opt/mycopunk-swag-store && git pull && docker compose up -d --build"