CollectorHub

A community-first social platform for collectors — showcase, discover, connect, and trade peer-to-peer. Instagram-meets-marketplace for hobby collectors (action figures, designer toys & blind boxes, model kits & Lego, diecast).

Structure

colelctorgram/
├── frontend/        # Next.js (App Router) web app + admin console
├── backend/         # FastAPI (Python) API — REST + WebSocket
├── design_v3/       # v3 "New frontend" design — full LOCAL mirror (read off disk; no MCP). See design_v3/README.md
└── .claude/         # Project notes, tech-stack decisions, history (gitignored)

The Expo mobile app is Phase 2 — not in this repo yet.

Stack

Layer	Choice
Web + Admin	Next.js 16 (App Router, TypeScript, Tailwind)
Backend	Python + FastAPI + SQLAlchemy 2.0 (async) + Alembic
Database	PostgreSQL
Media	Cloudflare R2 (presigned upload)
Search	PostgreSQL ILIKE (no external search service in Phase 1)
Realtime	FastAPI WebSocket, in-process manager (single instance)
Background jobs	asyncio periodic tasks (no Redis/broker in Phase 1)

No Redis, ARQ, or Meilisearch in Phase 1 — see Decisions Log for the rationale and when to add them back.

Local development

Requires python3, node, npm, and docker.

./run.sh                 # docker (postgres) + migrate + backend (:8000) + frontend (:3000)
./run.sh --backend-only  # API only
./run.sh --frontend-only # web only
./run.sh --no-docker     # use an external Postgres

Copy backend/.env.example → backend/.env and frontend/.env.local (set NEXT_PUBLIC_API_URL). Seed login after migrations: [email protected] / seed_pass_1!.

Deployment

• Backend → Railway (Singapore region) via backend/Dockerfile; managed Postgres plugin in the same region. railway.toml runs alembic upgrade head then starts uvicorn.
• Frontend → Cloudflare Pages (set NEXT_PUBLIC_API_URL to the Railway URL).
• Media → Cloudflare R2.

Set APP_ENV=production plus a strong SECRET_KEY, DATABASE_URL, FRONTEND_URL, and R2 credentials — the backend refuses to start in production with insecure defaults. Target cost ~$10–20/month through early Phase 1. Full plan and migration path (to an in-country Mumbai VPS later) in the Decisions Log.

Docs

• Project Overview
• Tech Stack
• Architecture
• Database Design
• Decisions Log
• Implementation TODO

Status

Phase 1 — web app + admin console built (real API, mock removed). Deploy-ready (Dockerfile + Railway config + production guards). Remaining before public launch: backend test suite + CI. See TODO. Mobile app is Phase 2; payments/livestream/ML are Phase 3.