2025 08 03 Initial Setup - eightythreeapps/collectr GitHub Wiki

2025-08-03: Initial Setup & Foundation

📅 Session Info

  • Date: 2025-08-03
  • Duration: ~3 hours
  • Developer(s): Ben Reed + Claude Code
  • Session Type: Setup & Foundation

🎯 Goals

  • Set up monorepo structure with proper TypeScript configuration
  • Initialize Firebase project and deploy security rules
  • Create working local development environment
  • Integrate IGDB API for game search functionality
  • Deploy initial web application to Firebase Hosting
  • Set up GitHub repository with CI/CD foundations

🏁 Starting State

What was the state of the project at the start?

  • Empty project with only PRD document
  • No code infrastructure
  • No Firebase project
  • No development environment

📝 Work Log

10:00 - Project Foundation Setup

What was done:

  • Created monorepo structure with pnpm workspaces
  • Set up /apps, /packages, /infrastructure, /firebase directories
  • Configured TypeScript with strict settings across all packages
  • Created shared types package with Zod schemas

Code Changes:

mkdir -p apps/{web,api,workers} packages/{types,eslint-config} infrastructure/terraform firebase
pnpm init

Key Files Created:

  • package.json (root workspace config)
  • pnpm-workspace.yaml
  • packages/types/src/{game,shelf,user,api}.ts (Zod schemas)

11:00 - Next.js Web App Setup

What was done:

  • Scaffolded Next.js 14 with App Router
  • Configured Tailwind CSS + Radix UI
  • Set up Firebase SDK integration
  • Created responsive landing page

Code Changes:

// apps/web/src/lib/firebase.ts - Firebase configuration
export const auth = getAuth(app);
export const db = getFirestore(app);
export const storage = getStorage(app);

12:00 - Fastify API Server

What was done:

  • Created Fastify server with TypeScript
  • Implemented Firebase Admin SDK integration
  • Built authentication middleware with public/private route handling
  • Created route stubs for games, shelves, users

Code Changes:

// apps/api/src/middleware/auth.ts
const PUBLIC_ROUTES = ['/health', '/v1/games/search'];

13:00 - Firebase Project Setup

What was done:

  • Created Firebase project collectr-8ae95
  • Enabled Firestore, Storage, Authentication, Hosting
  • Deployed security rules with deny-by-default posture
  • Configured Firestore indexes for optimal queries

Code Changes:

firebase use collectr-8ae95
firebase deploy --only firestore:rules,storage:rules,firestore:indexes

14:00 - IGDB API Integration

What was done:

  • Registered Twitch application for IGDB access
  • Implemented IGDBService with OAuth token management
  • Added RAWG API fallback service
  • Created intelligent game search with relevance scoring
  • Fixed authentication middleware URL parsing issue

Code Changes:

// Game search working with real IGDB data
curl "http://localhost:3001/v1/games/search?q=mario"
// Returns: Nintendo games with cover art, descriptions, metadata

15:00 - Deployment to Firebase Hosting

What was done:

  • Configured Next.js for static export
  • Built and deployed web application
  • Resolved Firebase hosting configuration issues
  • Successfully deployed to https://collectr-8ae95.web.app

Code Changes:

// next.config.js
const nextConfig = {
  output: 'export',
  trailingSlash: true,
};

✅ Achievements

  • Monorepo Foundation: Fully working TypeScript monorepo with pnpm
  • Firebase Integration: Complete backend setup with security rules
  • Local Development: Working dev environment with hot reload
  • Game Search API: Real IGDB data integration working perfectly
  • Web Deployment: Live application on Firebase Hosting
  • Type Safety: End-to-end TypeScript with Zod validation

🚀 Deployments

🐛 Issues Encountered

Issue 1: ESLint Version Conflicts

Problem: TypeScript ESLint parser incompatible with ESLint v9 Solution: Updated to @typescript-eslint v8 and relaxed strictOptionalPropertyTypes Prevention: Pin dependency versions in shared ESLint config

Issue 2: Firebase Admin Initialization Timing

Problem: Firebase services accessed before initialization Solution: Moved service exports inside initializeFirebase function Prevention: Always initialize services after app setup

Issue 3: Authentication Middleware URL Parsing

Problem: Query parameters in URL prevented public route matching Solution: Parse pathname separately from full URL Prevention: Always test route matching with query parameters

Issue 4: Next.js Static Export Configuration

Problem: Default Next.js build doesn't create exportable static files Solution: Added output: 'export' to next.config.js Prevention: Configure static export from the beginning for hosting deployments

🧠 Learnings & Insights

  • Monorepo Benefits: Shared types across frontend/backend eliminated many integration issues
  • Firebase Security: Deny-by-default rules with explicit allow patterns provide robust security
  • IGDB API: Requires server-to-server OAuth flow, not redirect-based authentication
  • Development Workflow: Having working local environment before production deployment saves time
  • Type Safety: Zod schemas provide runtime validation + TypeScript types from single source

📋 Next Session TODOs

  • Authentication UI: Build Google/Apple sign-in components
  • Game Search Interface: Create search UI connected to working API
  • Collection Management: Implement "Add to Shelf" functionality
  • User Profiles: Build user account and shelf management
  • Cloud Run Deployment: Deploy API server to production
  • Custom Domain: Set up collectr.app domain

🔗 References

📊 Metrics

  • Lines of code added: ~2,500
  • Files created: 45+
  • Dependencies added: 25+
  • Build time: <60 seconds
  • API response time: <300ms (meets PRD requirement)

Final State

What's the project state at the end of this session?

  • ✅ Fully working local development environment
  • ✅ Real game search with IGDB integration
  • ✅ Live web application deployment
  • ✅ Firebase backend with security rules
  • ✅ Type-safe API with authentication

Test URLs:

Next Session Priority: Build authentication UI and game search interface to complete core user journey (U1, U2, U3 from PRD)

Session completed: 2025-08-03 21:30