115 lines
3.0 KiB
Markdown
115 lines
3.0 KiB
Markdown
# 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"
|
|
```
|