WorkSphere

The Intelligent Multi-Agent Workspace Discovery & Real-Time Booking Engine

🌟 Official Selected Project for ECSoC 2026 (Elite Coders Summer of Code) & OSCI 2026 (Open Source Contribution India) 🌟

WorkSphere is an autonomous multi-agent ecosystem engineered for remote professionals, digital nomads, and distributed teams.
Discover top-tier cafes, coworking spaces, and quiet libraries dynamically ranked on WiFi speeds, power outlet density, real-time noise metrics, and live seating occupancy.

🚀 Launch Live Demo • ✨ Features • 🏗️ Architecture • ⚡ Quickstart • 👥 Contributors (99) • 🐛 Report Issue

👑 Project Leadership & Authorship

Role	Leader	GitHub	Badges
🚀 Founder & Lead Architect / CTO	Satyam Pandey	@SatyamPandey-07

Tip

Issue Claiming & Auto-Merge Workflow:

Post /claim on any open issue to auto-assign it to yourself (limit: up to 10 active issues, 6-day completion window).
Post /unclaim on an issue to unassign yourself if you need to release it for other contributors!
When opening a PR, link the issue (e.g. Closes #123). Our CI will automatically approve and squash-merge your PR with co-author credit!

🚀 Contributors (99 Active Rockstars)

A massive thank you to all 99 brilliant contributors and bots building WorkSphere! 🌟

_{SatyamPandey-07} _{👑 Creator}	_jasonjose007	_Ayush-0918	_{SanjanaTech19}	_ErebAsh	_{zainabhina05-png}	_{Pratyush-Panda-2006}
_Babin123456	_{sanskarcoder29}	_{prasiddhi-105}	_{sanjana2505006}	_{harshit-kumar-dev}	_{Vachhani-Tapan}	_Jivan-Patel
_leenacags	_Chirag1724	_Jidnyasa-P	_Jashvanthan	_diksha78dev	_MILAN-123865	_{Prathvikmehra}
_rishab11250	_{gauri9368gupta-maker}	_{sumittiwari1302}	_Shruti070107	_{shahkhushi0307}	_{Huzaifaahmedbhutto}	_Aditya8369
_hemnath-hub	_Tanishkkkkk	_Aryanbuha890	_Kushal-prime	_{vigneshwaran484}	_Diwakar-odds	_{revatikadam0607}
_marisa-mmm	_{anushkanikam05}	_{khushimalani16}	_varshu55	_Ruchira807	_Janvi-kapoor	_{anshika-guleria}
_{Aakansha-saroj-05}	_csxark	_shadab-6718	_harshith7002	_Aakif-Kohari	_{nithinoffizial}	_Kadaliswarna
_SoumalyaSaha	_Senthil455	_{pranav28042007-boop}	_{Sahan20030814}	_{khedkaravani-rgb}	_Komal290106	_{hirthicksundar1980-debug}
_rudreshborle	_{Vishvapatel2047}	_{Yuva-Deekshitha-N}	_yashvi-3106	_afifasyed123	_itsaditi05	_{SpiliosDimakopoulos}
_{panditshubham766-dotcom}	_{HimanshuPathak2725}	_Daksh7785	_{badshahaditya57-sketch}	_SujalKamate	_RitikaSen27	_Parshant-12
_{punithkumar-060308}	_{Bheemeswari497}	_AndrewJefrin	_{onitshubham14}	_{nishthagupta09}	_{karrisanthoshigayatri}	_{jenniferramesh423-cmyk}
_{VarunikaShreeS}	_Aditya90456	_Suprita736	_{saurabhwagh01}	_{sagar-18-07-2006}	_s-reeshma	_RajD2910
_piush365	_{prajapati-pankaj-31}	_{Gautam-Bharadwaj}	_keshav33450	_{Keerthi-10-05}	_Jaswanth1617	_{jiahshifana08}
_{Gunjan10-droid}	_Gabyee17	_Falguni-105	_Kruthica	_Prathibha-ui	_{codinggujarat}	_{dependabot[bot]} _{🤖 Bot}
_{github-actions[bot]} _{🤖 Bot}

✨ 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:

Navigate to about:config in Firefox.
Search for media.webspeech.recognition.enable and set it to true.
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

🌟 Core Platform Capabilities

WorkSphere brings together geospatial data, ambient intelligence, and real-time collaboration into a unified, responsive interface:

Capability	Experience	Technical Highlight
🗺️ Interactive Geospatial Map	Dynamic CartoDB Dark Matter tiles with color-coded venue noise markers (green=quiet, amber=moderate, red=busy).	Real road routing with OSRM, Haversine proximity, custom Clerk user pins.
🤖 Autonomous Multi-Agent AI	Conversational discovery agent that reasons across amenities, seating availability, and workspace preferences.	5-agent pipeline (Orchestrator → Context → Data → Reasoning → Action) with transparent thought telemetry.
📡 Live Presence & Telemetry	Real-time seat occupancy badges (Quiet, Moderate, Busy) and collaborative workspace notes.	Sub-50ms WebSocket synchronization powered by PartyKit mesh network.
🔋 Battery Panic Mode	Automatically re-ranks search results when battery drops below 20%, prioritizing verified desk outlets.	Web Battery API integration with graceful degradation on non-supported viewports.
📴 Offline-First PWA	Browse cached venues, view floor plans, and queue check-ins completely offline.	Service Worker background sync + IndexedDB storage + Web Locks API synchronization.
🧾 Cryptographic PDF Invoicing	Instant one-click PDF receipts generated for verified bookings.	100% serverless, zero-filesystem execution via `pdf-lib` with embedded Helvetica glyphs.
🎓 Zero-Knowledge Student Perks	Claim verified student discounts without revealing personal academic credentials.	Client-side WASM ZKP proof generation with offline localStorage verification caching.

🛠️ 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

Clone the repository

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

Install dependencies
```
npm install
```
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
```
Initialize Database Schema
```
npx prisma generate
npx prisma db push
```
Run the development server
```
npm run dev
```
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_...

# (optional) Gemini API key — used for server-side venue summaries
GEMINI_API_KEY=your_gemini_key_here

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

The venue summary endpoint sends its prompt to Gemini rather than the chat models. See docs/GEMINI_INTEGRATION.md for the client contract, model choice, error handling, and test setup.

📁 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

Open the app at http://localhost:3000
Allow location access when prompted
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

Open the app in Chrome or Edge
Click the microphone icon in the chat input bar
Allow microphone permission when prompted
Speak your query — it will populate the text input automatically
Click Send or press Enter to submit

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

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

⭐ Favorites & Ratings (Requires Sign-in)

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

📱 PWA Installation

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

🚀 Deployment

Deploy to Vercel

Push to GitHub
Connect repository to Vercel
Add environment variables
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 & Issue Workflow

Contributions are warmly welcomed! We aim to make contributing as smooth and rewarding as possible.

⚡ Automated Issue Assignment

Find an Issue: Explore our Open Issues.
Claim with /claim: Drop a comment containing /claim on any unassigned issue. The automation will assign it to you instantly!
- You can hold up to 10 active assigned issues at once.
- Recommended completion window is 6 days.
Release with /unclaim: If you need to step away from an issue, simply comment /unclaim to release it for other contributors.
Auto-Merge on PR: Include Closes #<issue_number> in your PR description. When opened, CI checks the issue link and automatically squash-merges your PR with co-author credit!

Please refer to our Contributing Guide and Code of Conduct.

📄 License

This project is licensed under the MIT License.

👨‍💻 Author

Satyam Pandey

GitHub: @SatyamPandey-07

⭐ Star this repo if you find it helpful!

Made with ❤️ by Satyam Pandey

Name		Name	Last commit message	Last commit date
.agents		.agents
.claude		.claude
.github		.github
.husky		.husky
.vscode		.vscode
circuits		circuits
context-compression		context-compression
docs		docs
e2e		e2e
party		party
prisma		prisma
public		public
scripts		scripts
src		src
wasm		wasm
worker		worker
.env.example		.env.example
.gitignore		.gitignore
.nvmrc		.nvmrc
AGENTS.md		AGENTS.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
README.md		README.md
components.json		components.json
docker-compose.yml		docker-compose.yml
eslint.config.mjs		eslint.config.mjs
jest.config.js		jest.config.js
jest.setup.js		jest.setup.js
next.config.ts		next.config.ts
package-lock.json		package-lock.json
package.json		package.json
partykit.json		partykit.json
playwright.config.ts		playwright.config.ts
postcss.config.mjs		postcss.config.mjs
prisma.config.ts		prisma.config.ts
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation