# abhishek-jose7/hangout architecture

> Architecture diagram of the GitHub repository abhishek-jose7/hangout, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/abhishek-jose7/hangout
- Repository: https://github.com/abhishek-jose7/hangout

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend (Next.js App Router + React)" 
        direction TB
        FR["Pages & Layout\n(src/app)"]:::frontend
        FC["Shared UI Components\n(src/components)"]:::frontend
        FU["UI Primitives\n(src/components/ui)"]:::frontend
        HK["Hooks\n(src/hooks)"]:::frontend
        CPAuth["AuthProvider\n(src/components/AuthProvider.tsx)"]:::frontend
        CPNotif["NotificationProvider\n(src/components/NotificationProvider.tsx)"]:::frontend
        ST1["tailwind.config.js"]:::frontend
        ST2["postcss.config.mjs"]:::frontend
        ST3["globals.css"]:::frontend
        ST4["src/app/globals.css"]:::frontend
    end

    %% API Layer
    subgraph "API Layer (Next.js API Routes)" 
        direction TB
        API_G["Groups Domain\n/src/app/api/groups"]:::backend
        API_M["Members Domain\n/src/app/api/members"]:::backend
        API_V["Votes Domain\n/src/app/api/votes"]:::backend
        API_S["Share Domain\n/src/app/api/share"]:::backend
        API_L["Locations Domain\n/src/app/api/locations"]:::backend
        API_GC["Geocode Domain\n/src/app/api/geocode"]:::backend
        API_GT["Gemini-Test Domain\n/src/app/api/gemini-test"]:::backend
        API_T["Test DB Domain\n/src/app/api/test-db"]:::backend
        API_LS["Legacy Socket Endpoint\n/src/pages/api/socket.js"]:::backend
    end

    %% Real-Time Service
    subgraph "Real-Time Service (Socket.io)" 
        direction TB
        RT["Socket.io Server\n(socket.js, socket.ts)"]:::realtime
    end

    %% Database
    DB["Supabase\n(PostgreSQL)"]:::database

    %% External Services
    subgraph "External Services" 
        direction TB
        EX_C["Clerk Auth\n(OAuth)"]:::external
        EX_GM["Google Gemini API"]:::external
        EX_GE["Geocoding API"]:::external
        EX_MAP["Google Maps API"]:::external
    end

    %% Connections
    Browser["User Browser"]:::external -->|loads UI| FR
    FR -->|calls OAuth Flow| EX_C
    FR -->|REST calls| API_G
    FR -->|REST calls| API_M
    FR -->|REST calls| API_V
    FR -->|REST calls| API_S
    FR -->|REST calls| API_L
    FR -->|REST calls| API_GC
    FR -->|REST calls| API_GT
    FR -->|REST calls| API_LS
    API_G -->|reads/writes| DB
    API_M -->|reads/writes| DB
    API_V -->|reads/writes| DB
    API_S -->|reads/writes| DB
    API_L -->|reads/writes| DB
    API_GC -->|fetch geocode| EX_GE
    API_GT -->|AI suggestions| EX_GM
    FR <-->|real-time events| RT
    FR -->|map data| EX_MAP

    %% Click Events
    click FR "https://github.com/abhishek-jose7/hangout/tree/main/src/app"
    click FC "https://github.com/abhishek-jose7/hangout/tree/main/src/components"
    click FU "https://github.com/abhishek-jose7/hangout/tree/main/src/components/ui"
    click HK "https://github.com/abhishek-jose7/hangout/blob/main/src/hooks/useAuth.ts"
    click HK "https://github.com/abhishek-jose7/hangout/blob/main/src/hooks/useSocket.ts"
    click HK "https://github.com/abhishek-jose7/hangout/blob/main/src/hooks/useRealtime.ts"
    click CPAuth "https://github.com/abhishek-jose7/hangout/blob/main/src/components/AuthProvider.tsx"
    click CPNotif "https://github.com/abhishek-jose7/hangout/blob/main/src/components/NotificationProvider.tsx"
    click ST1 "https://github.com/abhishek-jose7/hangout/blob/main/tailwind.config.js"
    click ST2 "https://github.com/abhishek-jose7/hangout/blob/main/postcss.config.mjs"
    click ST3 "https://github.com/abhishek-jose7/hangout/blob/main/globals.css"
    click ST4 "https://github.com/abhishek-jose7/hangout/blob/main/src/app/globals.css"
    click API_G "https://github.com/abhishek-jose7/hangout/blob/main/src/app/api/groups/route.ts"
    click API_M "https://github.com/abhishek-jose7/hangout/blob/main/src/app/api/members/route.ts"
    click API_V "https://github.com/abhishek-jose7/hangout/blob/main/src/app/api/votes/route.ts"
    click API_S "https://github.com/abhishek-jose7/hangout/blob/main/src/app/api/share/[code]/route.ts"
    click API_L "https://github.com/abhishek-jose7/hangout/blob/main/src/app/api/locations/route.ts"
    click API_GC "https://github.com/abhishek-jose7/hangout/blob/main/src/app/api/geocode/route.ts"
    click API_GT "https://github.com/abhishek-jose7/hangout/blob/main/src/app/api/gemini-test/route.ts"
    click API_T "https://github.com/abhishek-jose7/hangout/blob/main/src/app/api/test-db/route.ts"
    click API_LS "https://github.com/abhishek-jose7/hangout/blob/main/src/pages/api/socket.js"
    click RT "https://github.com/abhishek-jose7/hangout/blob/main/socket.ts"
    click RT "https://github.com/abhishek-jose7/hangout/blob/main/socket.js"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366D6,stroke-width:1px
    classDef backend fill:#D6F5D6,stroke:#228B22,stroke-width:1px
    classDef realtime fill:#FFEACC,stroke:#FF8C00,stroke-width:1px
    classDef database fill:#E6D0FF,stroke:#800080,stroke-width:1px
    classDef external fill:#F0F0F0,stroke:#808080,stroke-dasharray: 5 5,stroke-width:1px
```
