How abhishek-jose7/hangout works
Project Type and Purpose
• This is a full-stack web application (“Hangout Planner”) built on Next.js 15 with a React TypeScript front end and Next.js API Routes on the back end.
• Purpose: Plan group meetups with AI-powered location suggestions (Google Gemini), democratic voting, real-time coordination (Socket.io), and persistent storage in Supabase (PostgreSQL). Authentication is handled by Clerk (Google OAuth).
Main Components
a. Frontend (Next.js App Router)
• Pages & Layout (src/app/*) – React components and pages under the new App Router (e.g., /create, /dashboard, /group/[code]).
• Shared UI Components (src/components, src/components/ui) – Buttons, inputs, maps, hero sections, etc.
• Hooks & Context Providers (src/hooks, src/components/AuthProvider.tsx, NotificationProvider.tsx) – manage auth state, real-time updates, sockets.
• Styling – Tailwind CSS (tailwind.config.js), globals.css.
b. Backend API (Next.js API Routes)
• REST endpoints (src/app/api/* & src/pages/api/socket.js) – groups, members, votes, share, geocode, Gemini-test, etc.
• Business logic in route handlers (route.ts) and shared lib functions (src/lib/*).
• Server middleware (src/middleware.ts) – global request handling (e.g., auth checks).
c. Real-Time Layer (Socket.io)
• Server socket implementation (socket.ts, src/lib/socket.ts) integrated with the Next.js server or as a small Node.js service.
• Client socket hook (src/hooks/useSocket.ts) for live vote updates and map tracking.
d. Database (Supabase / PostgreSQL)
• Tables: groups, members, itinerary_votes (defined in scripts and README SQL).
• Client library: src/lib/supabase.ts (Supabase JS client).
• Migration & setup scripts (scripts/*.sql, scripts/setup-database.js).
e. External Services
• Clerk Auth – Google OAuth provider for user sign-in (configured via environment variables).
• Google Gemini API – AI service for location suggestions (via src/lib/gemini.ts).
• Geocoding API (optional, via /api/geocode route).
• Maps (Google Maps Places API) – interactive map in UI, environment variable MAPS_API_KEY.
Relationships & Data Flows
• User Browser → Next.js Frontend (SSR / client-side React)
• Frontend ↔ Clerk Auth (OAuth flow)
• Frontend → Next.js API Routes (fetchWithAuth, fetch calls)
• API Routes → Supabase → PostgreSQL
• API Routes → External AI (Gemini) or Geocode API
• Frontend ↔ Socket.io server (real-time events for votes, live tracking)
• Supabase hosts persistent data; Socket.io keeps ephemeral real-time state in sync.
Architectural Patterns & Design Principles
• Monolithic full-stack with clear separation of concerns: UI, API, data, real-time.
• App Router pattern in Next.js for organizing pages and API routes.
• React Context and custom hooks for cross-cutting concerns (auth, sockets).
• “lib” folder for shared utilities (DRY).
• Serverless-style API Routes (fits Vercel deployment).
• Scripts folder for database setup/migrations.
Drill-Down Details
• Inside Frontend, group pages (Create, Dashboard, Group/[code], Join, Share, Auth pages) and shared UI components.