Skip to content

About

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

ย 
ย 

Latest commit

ย 

History

1,443 Commits

Folders and files

NameName
Last commit message
Last commit date
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 

Repository files navigation

๐Ÿข WorkSphere - AI-Powered Remote Workspace Finder

WorkSphere Banner

Next.js TypeScript Prisma Tailwind CSS Tests PWA Ready

A multi-agent AI platform that helps remote workers discover ideal workspaces like cafes, coworking spaces, and libraries based on WiFi quality, power outlets, noise levels, and more.

๐Ÿš€ Live Demo โ€ข ๐Ÿ› Report Bug


๐Ÿ‘‘ Project Leadership & Authorship

๐Ÿ”” Update for Contributors:

The limit for active assigned issues per person has been increased to 10 (previously 5).

You can claim any open issue by posting a comment with exactly: /claim

You will have 6 days to complete it! ๐Ÿš€

๐Ÿš€ Contributors (88 Active Rockstars)

Thanks to all 88 contributors building WorkSphere!

WorkSphere Contributors

๐Ÿ“‹ Table of Contents


โœจ Features

๐Ÿค– AI-Powered Search

  • Natural Language Queries: "Find a quiet cafe with good WiFi near me"
  • Smart Intent Understanding: Extracts work type, amenities, location preferences
  • Intelligent Scoring: Ranks venues based on work-friendliness criteria

๐ŸŽ™๏ธ Voice Input (Browser Support)

The chatbot supports voice-to-text via the Web Speech API:

Browser Voice Input
Chrome 33+ โœ… Supported
Edge 79+ โœ… Supported
Safari (desktop/mobile) โœ… Supported (webkit prefix)
Firefox Stable โš ๏ธ Not supported by default
Firefox Nightly โš ๏ธ Requires flag โ€” see below

Firefox users: The Web Speech API is disabled by default. To enable it:

  1. Navigate to about:config in Firefox.
  2. Search for media.webspeech.recognition.enable and set it to true.
  3. Reload the application.

When voice input is unavailable, a clear warning banner is displayed and the feature degrades gracefully โ€” the text input remains fully functional.

๐Ÿ—บ๏ธ Interactive Dark Theme Map

  • Dark Theme: Beautiful CartoDB Dark Matter tiles
  • Real-time Markers: Purple glowing venue markers with venue photos
  • Green Route Lines: Real road routing with OSRM (not straight lines)
  • User Location: Custom marker with Clerk user avatar
  • Auto-centering: Map adjusts to show search results
  • Dark Popups: Styled popups matching the theme

๐Ÿ“ก Real-time Venue Updates (NEW)

  • Server-Sent Events (SSE): Live venue data pushed from server to client
  • Live Ratings: See new reviews appear instantly without refreshing
  • Availability Updates: Crowd levels update in real-time
  • Stable Connections: Smart reconnect logic prevents connection spam

๐Ÿ“ธ Venue Photos (NEW)

  • Pexels Integration: High-quality venue photos via Pexels API
  • Server-side Proxy: API key never exposed to the browser
  • DB Caching: Each venue fetched once, then served from cache
  • Lazy Loading: Skeleton shimmer while photo loads, graceful fallback on error
  • Free tier: 20,000 requests/month, no billing required

๐Ÿข Venue Enrichment (100% FREE APIs)

  • OpenStreetMap Integration: Real venue data from OSM Overpass API
  • Amenities Display: WiFi, outdoor seating, accessibility from OSM
  • Opening Hours: Real business hours when available
  • No Credit Card Required: All APIs are completely free

๐Ÿ›ฃ๏ธ Real Road Routing

  • OSRM Integration: Actual road paths instead of straight lines
  • Turn-by-turn Geometry: Realistic routes on the map
  • Distance Calculation: Accurate road distance to venues
  • Multiple Profiles: Walking, driving, cycling routes

๐ŸŽฏ Multi-Agent Architecture

  • 5 Specialized AI Agents working together:
    • Orchestrator โ†’ Context โ†’ Data โ†’ Reasoning โ†’ Action
  • Transparent Reasoning: See each agent's thought process
  • Parallel Processing: Efficient query handling

โญ User Features

  • Favorites System: Save frequently visited spots
  • Crowdsourced Ratings: Rate venues on WiFi quality, outlets, noise levels, quietness
  • Rating Dialog: Beautiful modal with 5-star ratings for each amenity
  • Conversation History: Resume previous searches
  • Venue Suggestions: Submit new venues via modal form
  • Profile Dashboard: Complete analytics dashboard showing booking history
  • "NEURAL LEDGER": Futuristic booking history with confirmation IDs, dates, venue details
  • Download Receipts: PDF receipts for each booking with automatic download
  • View on Map: External link button to view booked venues on the interactive map
  • Booking Status: Visual status badges (Confirmed, Pending, Cancelled)

๐Ÿ” Authentication

  • Clerk Integration: Secure sign-in/sign-up
  • User Profiles: Personalized experience
  • Webhook Sync: Real-time user data updates

๏ฟฝ PDF Receipt System

  • Serverless-Compatible: Uses pdf-lib (not PDFKit) for AWS Lambda compatibility
  • Instant Generation: PDF receipts generated on-demand for confirmed bookings
  • Professional Format: Includes venue details, booking info, confirmation ID, timestamps
  • Embedded Fonts: Helvetica and HelveticaBold loaded from pdf-lib (no filesystem dependencies)
  • Direct Download: One-click download with loading states and error handling
  • Fixed Build Issues: Resolved Buffer/Uint8Array compatibility and cuid ID string handling

๏ฟฝ๐Ÿ“ฑ Progressive Web App (PWA)

  • Installable: Add to home screen on mobile/desktop
  • Offline Support: IndexedDB storage for venues and favorites
  • Service Worker: Caches static assets for fast loading
  • Background Sync: Queue actions when offline

๐Ÿš€ Performance & Reliability

  • Rate Limiting: API protection with configurable limits
  • Data Caching: Multi-layer caching with TTL support
  • Error Boundaries: Graceful error handling prevents crashes
  • Loading Skeletons: Smooth loading states for better UX

See docs/NEXTJS_PERFORMANCE_PLAYBOOK.md for a full guide on rendering strategies, bundle optimization, image optimization, caching, and Core Web Vitals measurement.

๐Ÿ“Š Analytics & Monitoring

  • Event Tracking: Track searches, venue interactions, agent performance
  • Agent Metrics: Monitor AI pipeline execution times
  • Search Patterns: Understand user behavior and preferences

๐Ÿงช Comprehensive Testing

  • 57 Unit Tests: Full coverage with Jest & React Testing Library
  • E2E Testing: Playwright configuration for end-to-end tests
  • API Tests: Route handler testing
  • Component Tests: UI component validation

๐Ÿ› ๏ธ Tech Stack

Category Technology
Framework Next.js 15.5 (App Router)
Language TypeScript 5.0
Styling Tailwind CSS 4.0, Custom UI Components
AI/LLM Groq SDK (Llama 3.3 70B)
Database Neon PostgreSQL + Prisma 7.2 ORM (with @prisma/adapter-pg)
Authentication Clerk
Maps React Leaflet + OpenStreetMap
Venue Data OpenStreetMap (Overpass API) - FREE
Venue Photos Pexels API - FREE (20k req/mo)
Real-time Server-Sent Events (SSE)
Routing OSRM (Open Source Routing Machine) - FREE
PDF Generation pdf-lib 2.x (serverless-compatible)
Testing Jest 29, React Testing Library, Playwright
PWA Service Workers + IndexedDB
Deployment Vercel

๐Ÿ—๏ธ Architecture

โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚                         USER INTERFACE                          โ”‚
โ”‚  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”  โ”‚
โ”‚  โ”‚      Map (70%)          โ”‚  โ”‚     Chat (30%)              โ”‚  โ”‚
โ”‚  โ”‚  - Venue Markers        โ”‚  โ”‚  - Natural Language Input   โ”‚  โ”‚
โ”‚  โ”‚  - User Location        โ”‚  โ”‚  - Agent Transparency       โ”‚  โ”‚
โ”‚  โ”‚  - Route Polylines      โ”‚  โ”‚  - Venue Cards              โ”‚  โ”‚
โ”‚  โ”‚  - Auto-centering       โ”‚  โ”‚  - Action Buttons           โ”‚  โ”‚
โ”‚  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜  โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
                                 โ”‚
                                 โ–ผ
โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚                      MULTI-AGENT PIPELINE                        โ”‚
โ”‚                                                                  โ”‚
โ”‚  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”    โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”    โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”      โ”‚
โ”‚  โ”‚ Orchestrator โ”‚ -> โ”‚   Context    โ”‚ -> โ”‚     Data     โ”‚      โ”‚
โ”‚  โ”‚    Agent     โ”‚    โ”‚    Agent     โ”‚    โ”‚    Agent     โ”‚      โ”‚
โ”‚  โ”‚              โ”‚    โ”‚              โ”‚    โ”‚              โ”‚      โ”‚
โ”‚  โ”‚ Routes query โ”‚    โ”‚ Extracts     โ”‚    โ”‚ Fetches      โ”‚      โ”‚
โ”‚  โ”‚ to agents    โ”‚    โ”‚ intent &     โ”‚    โ”‚ venues via   โ”‚      โ”‚
โ”‚  โ”‚              โ”‚    โ”‚ parameters   โ”‚    โ”‚ Overpass API โ”‚      โ”‚
โ”‚  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜    โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜    โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜      โ”‚
โ”‚                                                  โ”‚               โ”‚
โ”‚                                                  โ–ผ               โ”‚
โ”‚  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”    โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”                          โ”‚
โ”‚  โ”‚    Action    โ”‚ <- โ”‚  Reasoning   โ”‚                          โ”‚
โ”‚  โ”‚    Agent     โ”‚    โ”‚    Agent     โ”‚                          โ”‚
โ”‚  โ”‚              โ”‚    โ”‚              โ”‚                          โ”‚
โ”‚  โ”‚ Updates UI,  โ”‚    โ”‚ Scores &     โ”‚                          โ”‚
โ”‚  โ”‚ map, chat    โ”‚    โ”‚ ranks venues โ”‚                          โ”‚
โ”‚  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜    โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜                          โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
                                 โ”‚
                                 โ–ผ
โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚                         DATA LAYER                               โ”‚
โ”‚  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”  โ”‚
โ”‚  โ”‚  Neon Postgres  โ”‚  โ”‚   OpenStreetMap โ”‚  โ”‚     Clerk      โ”‚  โ”‚
โ”‚  โ”‚                 โ”‚  โ”‚                 โ”‚  โ”‚                โ”‚  โ”‚
โ”‚  โ”‚ - Users         โ”‚  โ”‚ - Overpass API  โ”‚  โ”‚ - Auth         โ”‚  โ”‚
โ”‚  โ”‚ - Venues        โ”‚  โ”‚ - Cafes         โ”‚  โ”‚ - User Sync    โ”‚  โ”‚
โ”‚  โ”‚ - Ratings       โ”‚  โ”‚ - Libraries     โ”‚  โ”‚ - Sessions     โ”‚  โ”‚
โ”‚  โ”‚ - Favorites     โ”‚  โ”‚ - Coworking     โ”‚  โ”‚                โ”‚  โ”‚
โ”‚  โ”‚ - Conversations โ”‚  โ”‚                 โ”‚  โ”‚                โ”‚  โ”‚
โ”‚  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜  โ”‚
โ”‚                                                                  โ”‚
โ”‚  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”                      โ”‚
โ”‚  โ”‚   Pexels API    โ”‚  โ”‚    OSRM API     โ”‚                      โ”‚
โ”‚  โ”‚                 โ”‚  โ”‚                 โ”‚                      โ”‚
โ”‚  โ”‚ - Venue Photos  โ”‚  โ”‚ - Road Routing  โ”‚                      โ”‚
โ”‚  โ”‚ - 20k/mo FREE   โ”‚  โ”‚ - Polylines     โ”‚                      โ”‚
โ”‚  โ”‚ - Server Proxy  โ”‚  โ”‚ - FREE          โ”‚                      โ”‚
โ”‚  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜                      โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

๐Ÿš€ Getting Started

Prerequisites

  • Node.js 18+
  • npm or yarn
  • Git
  • Docker and Docker Compose (Optional, but highly recommended for local Postgres & Redis)

Installation & Setup

  1. Clone the repository

    git clone https://github.com/SatyamPandey-07/WorkSphere.git
    cd WorkSphere
  2. Install dependencies

    npm install
  3. Choose your environment setup path:

    Option A: Docker Compose (Recommended)

    This starts a local PostgreSQL instance (with the pgvector extension) and Redis automatically.

    # Start database and Redis container services
    docker compose up -d
    
    # Copy local environment example
    cp .env.example .env.local
    # Fill out any missing external API keys in .env.local (e.g. Clerk, Groq)

    Option B: Manual Setup

    If you prefer not to use Docker:

    1. Setup a PostgreSQL 15+ database with the pgvector extension enabled.
    2. Optionally setup an Upstash Redis database.
    3. Copy environment config and fill in Neon and Upstash URLs:
      cp .env.example .env.local
  4. Initialize Database Schema

    npx prisma generate
    npx prisma db push
  5. Run the development server

    npm run dev
  6. Open in browser

    http://localhost:3000
    

๐Ÿงช Testing

Run All Tests

npm test

Watch Mode

npm run test:watch

End-to-End Tests

npm run test:e2e
npm run test:e2e:ui  # With UI

For a full guide on writing, running, and debugging Playwright tests, see docs/PLAYWRIGHT_TESTING_GUIDE.md.

Test Coverage

  • 57 Unit Tests covering:
    • API Route Handlers
    • React Components
    • Utility Functions
    • Rate Limiting
    • Analytics

๐Ÿ” Environment Variables

Create a .env.local file in the root directory by copying the template:

cp .env.example .env.local

Fill in the following values. Variables marked (required) must be set for the app to start; (optional) ones have local fallbacks.

# โ”€โ”€ Database โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€
# (required) Neon PostgreSQL connection string โ€” get from neon.tech
DATABASE_URL="postgresql://user:password@host/database?sslmode=require"

# โ”€โ”€ Authentication โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€
# (required) Clerk keys โ€” get from clerk.com > your app > API keys
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_SECRET_KEY=sk_test_...
NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up

# โ”€โ”€ AI โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€
# (required) Groq API key โ€” free at console.groq.com
GROQ_API_KEY=gsk_...

# โ”€โ”€ Venue Photos โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€
# (optional) Pexels API key โ€” falls back to placeholder images
PEXELS_API_KEY=your_pexels_key_here

# โ”€โ”€ Rate Limiting โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€
# (optional) Upstash Redis โ€” falls back to in-memory rate limiter
UPSTASH_REDIS_REST_URL=https://your-upstash-redis-endpoint.upstash.io
UPSTASH_REDIS_REST_TOKEN=your-upstash-redis-token

Full reference: See docs/ENV_VARS.md for a complete list of every variable with detailed descriptions.

You can obtain the Upstash Redis credentials from your Upstash Redis database dashboard.

The Upstash Redis variables are optional for local development. If UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN are omitted, the application falls back to an in-memory rate limiter. This allows the application to run locally without an Upstash Redis configuration, but rate-limit state is stored only in the local application memory and is not shared across multiple instances or processes.

For production or multi-instance deployments, configuring Upstash Redis is recommended to ensure consistent rate limiting across application instances.

Getting API Keys

Service URL Free Tier Required
Neon neon.tech 0.5GB storage โœ… Yes
Clerk clerk.com 10,000 MAU โœ… Yes
Groq console.groq.com Free API access โœ… Yes
Pexels pexels.com/api 20,000 req/month โŒ No (has fallback)
OSM/OSRM N/A Unlimited โŒ No (public API)

๏ฟฝ Pages

Route Page Description
/ Landing Page Hero section with product mockup, features showcase, CTAs
/ai AI Workspace Finder Main app with 70/30 map/chat split, dark theme
/dashboard User Dashboard Personal dashboard for authenticated users
/offline Offline Page PWA fallback when network unavailable
/sign-in Sign In Clerk authentication sign-in page
/sign-up Sign Up Clerk authentication sign-up page

๏ฟฝ๐Ÿ”Œ API Routes

Method Route Description
POST /api/chat Main chat endpoint with agent pipeline
GET /api/venues Search venues
POST /api/venues Add crowdsourced venue
GET /api/venues/enrich Enrich venue with OSM + Pexels data
POST /api/venues/[id]/rate Rate a venue
POST /api/venues/updates Bulk update venue photos
GET /api/favorites Get user's favorites
POST /api/favorites Add favorite
DELETE /api/favorites Remove favorite
GET /api/conversations List conversations
POST /api/conversations Create conversation
GET /api/conversations/[id] Get conversation
DELETE /api/conversations/[id] Delete conversation
GET /api/location IP-based location fallback
POST /api/webhook Clerk webhook for user sync

๐Ÿค– Multi-Agent System

Agent Pipeline Flow

User Query: "Find a quiet cafe with WiFi near me"
                    โ”‚
                    โ–ผ
โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚           ORCHESTRATOR AGENT                 โ”‚
โ”‚  โ€ข Analyzes query type                      โ”‚
โ”‚  โ€ข Determines: Context โ†’ Data โ†’ Reasoning   โ”‚
โ”‚  โ€ข Output: agentsToUse[], reasoning         โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
                    โ”‚
                    โ–ผ
โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚             CONTEXT AGENT                    โ”‚
โ”‚  โ€ข Extracts intent: workType = "focus"      โ”‚
โ”‚  โ€ข Parameters: amenities = [wifi, quiet]    โ”‚
โ”‚  โ€ข Output: structured intent object         โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
                    โ”‚
                    โ–ผ
โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚              DATA AGENT                      โ”‚
โ”‚  โ€ข Queries Overpass API for cafes           โ”‚
โ”‚  โ€ข Filters by location radius               โ”‚
โ”‚  โ€ข Output: venues[], conditions, meta       โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
                    โ”‚
                    โ–ผ
โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚            REASONING AGENT                   โ”‚
โ”‚  โ€ข Scores: WiFi(30%), Noise(25%),           โ”‚
โ”‚    Outlets(20%), Rating(15%), Distance(10%) โ”‚
โ”‚  โ€ข Ranks top venues with explanations       โ”‚
โ”‚  โ€ข Output: rankedVenues[], reasoning        โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
                    โ”‚
                    โ–ผ
โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚             ACTION AGENT                     โ”‚
โ”‚  โ€ข Updates map markers                      โ”‚
โ”‚  โ€ข Sets map view/zoom                       โ”‚
โ”‚  โ€ข Generates chat response                  โ”‚
โ”‚  โ€ข Output: UI updates, message              โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

Agent Transparency

The UI shows each agent's contribution:

๐Ÿง  Agent Pipeline (5 steps)
โ”œโ”€ ๐ŸŽฏ Orchestrator: Routing to Context, Data, Reasoning agents
โ”œโ”€ ๐Ÿ” Context: Extracted intent - focus work, needs WiFi
โ”œโ”€ ๐Ÿ“Š Data: Found 12 cafes within 2km radius
โ”œโ”€ ๐Ÿ’ก Reasoning: Top pick - Blue Bottle Coffee (score: 8.5/10)
โ””โ”€ โšก Action: Updated map with 5 markers

๐Ÿ“ Project Structure

The repository is a Next.js monorepo. Below is the top-level layout followed by a plain-English description of every major directory.

worksphere/
โ”œโ”€โ”€ prisma/                    # Database schema, migrations, and seed script
โ”œโ”€โ”€ party/                     # PartyKit real-time collaboration server
โ”œโ”€โ”€ docs/                      # Extended developer guides and reference docs
โ”œโ”€โ”€ e2e/                       # Playwright end-to-end tests
โ”œโ”€โ”€ public/                    # Static assets: PWA manifest, service worker, icons
โ”œโ”€โ”€ scripts/                   # Build and utility scripts
โ”œโ”€โ”€ src/
โ”‚   โ”œโ”€โ”€ __tests__/             # Jest unit and integration tests
โ”‚   โ”‚   โ”œโ”€โ”€ api/               # API route tests
โ”‚   โ”‚   โ”œโ”€โ”€ components/        # Component tests
โ”‚   โ”‚   โ””โ”€โ”€ lib/               # Utility tests
โ”‚   โ”œโ”€โ”€ app/                   # Next.js App Router pages, layouts, and API routes
โ”‚   โ”‚   โ”œโ”€โ”€ api/               # API route handlers
โ”‚   โ”‚   โ”‚   โ”œโ”€โ”€ chat/          # Multi-agent pipeline endpoint
โ”‚   โ”‚   โ”‚   โ”œโ”€โ”€ venues/        # Venue CRUD + OSM/Pexels enrichment
โ”‚   โ”‚   โ”‚   โ”œโ”€โ”€ favorites/     # User favorites
โ”‚   โ”‚   โ”‚   โ””โ”€โ”€ conversations/ # Chat history
โ”‚   โ”‚   โ”œโ”€โ”€ ai/                # Main workspace-finder page
โ”‚   โ”‚   โ”œโ”€โ”€ dashboard/         # User profile and booking dashboard
โ”‚   โ”‚   โ”œโ”€โ”€ sign-in/           # Clerk authentication pages
โ”‚   โ”‚   โ”œโ”€โ”€ sign-up/
โ”‚   โ”‚   โ”œโ”€โ”€ offline/           # PWA offline fallback
โ”‚   โ”‚   โ””โ”€โ”€ layout.tsx         # Root layout and global providers
โ”‚   โ”œโ”€โ”€ components/            # Reusable React UI components
โ”‚   โ”‚   โ”œโ”€โ”€ ai-elements/       # Agent-transparency and AI-specific UI pieces
โ”‚   โ”‚   โ””โ”€โ”€ ui/                # General design-system components
โ”‚   โ”œโ”€โ”€ context/               # React context providers for global client state
โ”‚   โ”œโ”€โ”€ core/                  # Core business logic and domain services
โ”‚   โ”œโ”€โ”€ hooks/                 # Custom React hooks (PWA, real-time, speech)
โ”‚   โ”œโ”€โ”€ lib/                   # Shared utilities, database client, rate limiting, analytics
โ”‚   โ”œโ”€โ”€ locales/               # Internationalisation (i18n) string files
โ”‚   โ”œโ”€โ”€ shaders/               # WebGL/GLSL shader source files
โ”‚   โ”œโ”€โ”€ types/                 # Shared TypeScript type definitions
โ”‚   โ”œโ”€โ”€ utils/                 # General-purpose helper functions
โ”‚   โ”œโ”€โ”€ wasm/                  # WebAssembly modules used in the browser
โ”‚   โ”œโ”€โ”€ worker/                # Service worker and background-sync logic
โ”‚   โ””โ”€โ”€ workers/               # Additional web worker scripts
โ”œโ”€โ”€ jest.config.js             # Jest configuration
โ”œโ”€โ”€ playwright.config.ts       # Playwright configuration
โ””โ”€โ”€ package.json

Key directories at a glance

Directory What it contains
prisma/ schema.prisma (data model), auto-generated migrations, and a seed script for local development
party/ PartyKit server (server.ts, multiRegionServer.ts) that powers real-time collaborative features via WebSockets
docs/ Hundreds of developer-facing guides covering architecture, testing, deployment, security, and more
e2e/ Playwright end-to-end test suites for full browser flows
public/ Static files served directly: service worker (sw.js), PWA manifest, and app icons
scripts/ One-off and CI utility scripts (database seeding, asset generation, etc.)
src/app/ Next.js 15 App Router โ€” every page, layout, and API route handler lives here
src/components/ Reusable React components: map, chatbot, venue cards, rating dialog, error boundary, and design-system primitives
src/context/ React context providers that share global state (currency, events, etc.) across the component tree
src/core/ Framework-agnostic business logic and domain services, kept separate from Next.js specifics
src/hooks/ Custom React hooks: usePWA, useRealTime (SSE), and useSpeechRecognition
src/lib/ Shared back-end helpers: Prisma client, Zod validation schemas, rate limiter, analytics, OSM/Pexels integration, and OSRM routing
src/locales/ Translation JSON files used by the i18n layer
src/shaders/ GLSL/WebGL shader programs for any GPU-accelerated rendering
src/types/ Project-wide TypeScript interfaces and enums
src/utils/ Lightweight, stateless helper functions shared across the codebase
src/wasm/ Compiled WebAssembly modules (e.g. FFT, noise filtering, SQLite FTS)
src/worker/ Service worker source and offline/background-sync logic
src/workers/ Additional dedicated web worker scripts (heavy computation off the main thread)
src/__tests__/ Unit and integration tests mirroring the src/ directory layout

๐Ÿงช Testing the App (User Guide)

Quick Start Test

  1. Open the app at http://localhost:3000
  2. Allow location access when prompted
  3. Start chatting with the AI assistant!

Feature Testing Checklist

๐Ÿ” AI Search

Try these natural language queries:

  • "Find a quiet cafe with good WiFi near me"
  • "Show me coworking spaces within 2km"
  • "I need a library to study"

๐ŸŽ™๏ธ Voice Input

  1. Open the app in Chrome or Edge
  2. Click the microphone icon in the chat input bar
  3. Allow microphone permission when prompted
  4. Speak your query โ€” it will populate the text input automatically
  5. Click Send or press Enter to submit

Testing the unsupported-browser warning (Firefox Nightly / DevTools simulation):

  1. Open Chrome DevTools (F12) โ†’ Console tab
  2. Paste: delete window.SpeechRecognition; delete window.webkitSpeechRecognition;
  3. Reload the page
  4. The mic button will appear dimmed/greyed out
  5. Click it โ†’ an amber warning banner appears explaining the limitation

โญ Favorites & Ratings (Requires Sign-in)

  1. Sign in with Clerk
  2. Click heart icon on venue cards to favorite
  3. Click "Rate" to submit ratings

๐Ÿ“ฑ PWA Installation

  • Desktop: Click install icon in browser
  • Mobile: "Add to Home Screen"

๐Ÿš€ Deployment

Deploy to Vercel

  1. Push to GitHub
  2. Connect repository to Vercel
  3. Add environment variables
  4. Deploy!

๐Ÿ”ฎ Future Improvements

Priority Feature Description
๐Ÿ”ด High Analytics Dashboard Admin page to view search patterns, popular venues, user metrics
๏ฟฝ Medium Mobile App React Native version sharing the same API backend
๐ŸŸก Medium AI Memory Cross-conversation learning for personalized recommendations
๐ŸŸก Medium Social Features Share favorite workspaces, follow other remote workers
๐ŸŸข Low Booking Integration Reserve desks at coworking spaces via API
๐ŸŸข Low Noise Level API Real-time noise monitoring hardware integration

๐Ÿค Contributing

Contributions are welcome! Please refer to our comprehensive Contributing Guide for details on:

  • Coding standards and styling.
  • Testing guidelines (Jest unit tests and Playwright E2E integration).
  • Required pre-commit quality checks to ensure Vercel build compatibility.

Please read our Code of Conduct.

To get started quickly:

  1. Fork the repository and create your feature branch (git checkout -b feature/amazing-feature).
  2. Implement your changes.
  3. Make sure all pre-commit checks pass (npm run lint, npx tsc --noEmit, and npm test).
  4. Commit your changes (git commit -m 'feat: Add amazing feature') and push to your branch.
  5. Open a Pull Request against the main branch.

๐Ÿ“„ License

This project is licensed under the MIT License.


๐Ÿ‘จโ€๐Ÿ’ป Author

Satyam Pandey


โญ Star this repo if you find it helpful!

Made with โค๏ธ by Satyam Pandey

About

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages