Architecture

System design, tech stack, and data flow

System Overview

HostelHack is a full-stack TypeScript application built on Next.js 15 App Router. The architecture follows a layered pattern: client → middleware → API → services → data.


┌─────────────────────────────────────────────────────────────────────┐
│                          CLIENT (Browser)                           │
│                                                                     │
│   Next.js 15 App Router  │  React 19  │  Tailwind CSS + shadcn/ui  │
│   Framer Motion          │  Zustand   │  React Hook Form + Zod     │
└──────────────────────────────┬──────────────────────────────────────┘
                               │
                        Clerk Middleware
                     (Auth + Route Protection)
                               │
┌──────────────────────────────┼──────────────────────────────────────┐
│                        API LAYER (Next.js)                          │
│                                                                     │
│  /api/hostels/search     — AI discovery + verification              │
│  /api/hostels/dossier    — AI intelligence reports                  │
│  /api/proposals          — CRUD proposals + email send              │
│  /api/inbox/*            — Email sync, threads, send, reply         │
│  /api/webhooks/*         — Gmail Pub/Sub + MS Graph push            │
│  /api/inngest            — Durable job execution endpoint           │
└──────────────┬──────────────────────────┬───────────────────────────┘
               │                          │
    ┌──────────▼──────────┐    ┌──────────▼──────────┐
    │   Gemini 2.0 Flash  │    │      Inngest         │
    │   (Google Gen AI)   │    │  (Background Jobs)   │
    │                     │    │                      │
    │  • Hostel search    │    │  • syncInbox         │
    │  • Dossier gen      │    │  • processWebhook    │
    │  • AI enrichment    │    │  • renewWatches      │
    └─────────────────────┘    └──────────────────────┘
               │                          │
    ┌──────────▼──────────────────────────▼───────────────────────────┐
    │                        DATA LAYER                               │
    │                                                                 │
    │   Supabase (PostgreSQL)           │  Firebase / Firestore       │
    │   • users, proposals, deals       │  • Users, proposals,        │
    │   • mail_threads, mail_messages   │    deals, messages          │
    │   • connected_mail_accounts       │  • Firestore Security Rules │
    │   • mail_attachments              │                             │
    │   • search_cache                  │  Supabase Storage           │
    │   • RLS policies on all tables    │  • Profile photos           │
    │   • Realtime subscriptions        │  • Attachments              │
    └─────────────────────────────────────────────────────────────────┘

Tech Stack

Layer	Technology	Purpose
Framework	Next.js 15 (App Router)	Full-stack React with SSR, API routes, middleware
UI	React 19 + Tailwind CSS 4 + shadcn/ui	Component library, design system, responsive
Animation	Framer Motion	Page transitions, micro-interactions
Authentication	Clerk	Email, Google, Microsoft SSO + session mgmt
Primary DB	Supabase (PostgreSQL)	Users, proposals, deals, email data with RLS + Realtime
Secondary DB	Firebase / Firestore	Document store with security rules
AI / LLM	Gemini 2.0 Flash	Discovery, dossier generation, email enrichment
Email	Gmail API + Microsoft Graph	Full email CRUD with OAuth 2.0
Background Jobs	Inngest	Durable execution, webhooks, scheduled sync
State	Zustand	Lightweight client-side state management
Validation	React Hook Form + Zod	Type-safe forms + schema validation
Storage	Supabase Storage + Cloudinary	Profile photos, attachments, CDN
Deploy	Vercel	Edge-optimized hosting, serverless functions

Data Flow

Hostel Discovery Flow

1User enters location + skills on /search page

2Client POSTs to /api/hostels/search

3Server checks search_cache in Supabase → return cached if fresh

4Gemini 2.0 Flash + Google Search Retrieval generates hostel list

5verifyWebsite() → HTTP HEAD validates each hostel URL

6scrapeContactEmails() → Crawls /contact, /about for emails

7verifyEmailDomain() → DNS MX validates each email domain

8Results cached in Supabase, returned to client

Email Sync Flow

1User connects Gmail/Outlook via OAuth (/api/inbox/connect/:provider)

2Tokens stored in connected_mail_accounts table

3Inngest syncInbox job triggers (scheduled or on-demand)

4Provider factory selects Gmail or Microsoft adapter

5Fetches up to 50 threads, batch-processes 10 at a time

6Threads + messages upserted to mail_threads / mail_messages

7Gmail Pub/Sub or Microsoft Graph webhook fires on new email

8processWebhookEvent job performs delta sync via cursor

9Supabase Realtime pushes changes to the frontend instantly

Infrastructure

Vercel

Edge-optimized hosting with serverless API Routes. Automatic deployments from GitHub main branch. Global CDN for static assets.

Supabase

Managed PostgreSQL with Row-Level Security, Realtime subscriptions, Storage buckets, and auto-generated REST APIs.

Inngest

Durable execution engine for background jobs. Automatic retries, rate limiting, scheduling, and event-driven triggers.

External Services

Clerk (auth), Google GenAI (Gemini), Gmail API, Microsoft Graph, Cloudinary (CDN), Firebase (secondary DB).

Project Structure

HostelHack/
├── app/
│   ├── (app)/             # Authenticated app routes (NomadOS)
│   │   ├── dashboard/     # Command center
│   │   ├── search/        # AI hostel discovery
│   │   ├── inbox/         # Unified email inbox
│   │   ├── proposals/     # Proposal management
│   │   ├── deals/         # Deal tracking
│   │   ├── reputation/    # Reviews & ratings
│   │   ├── profile/       # User profile
│   │   ├── matches/       # AI matching
│   │   └── settings/      # User settings
│   ├── hostel/            # HostelOS portal
│   ├── api/               # API routes
│   │   ├── hostels/       # Discovery + dossier
│   │   ├── inbox/         # Email integration
│   │   ├── proposals/     # Proposal CRUD
│   │   ├── webhooks/      # Gmail + Outlook push
│   │   └── inngest/       # Background job endpoint
│   ├── docs/              # This documentation
│   └── (public)/          # Landing, pricing, founders
├── components/            # Shared UI components (shadcn)
├── contexts/              # React contexts (Auth)
├── hooks/                 # Custom hooks
├── lib/
│   ├── mail/              # Email provider abstraction
│   │   ├── base.ts        # Interface contract
│   │   ├── google.ts      # Gmail implementation
│   │   ├── microsoft.ts   # Outlook implementation
│   │   └── factory.ts     # Provider auto-select
│   ├── email-verify.ts    # URL + MX verification
│   ├── supabase.ts        # DB client
│   └── firebase.ts        # Firebase client
├── inngest/               # Background job definitions
│   ├── client.ts          # Inngest client
│   └── functions.ts       # Job functions
└── supabase/
    └── migrations/        # Database schema migrations