# 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
```bash
docker compose up -d
```

### Run migrations
```bash
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
```bash
cd frontend
npx shadcn@latest add button  # or other component
```

## Environment Variables

See `.env.example` for all required variables.

## Testing

```bash
# Backend
cd backend
pytest

# Frontend
cd frontend
pnpm test
```

## Deployment

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

Manual deploy:
```bash
ssh netcup "cd /opt/mycopunk-swag-store && git pull && docker compose up -d --build"
```