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.
- Founder & CTO: Satyam Pandey
🔔 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:
/claimYou will have 6 days to complete it! 🚀
Thanks to all 59+ contributors building WorkSphere!
![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]"){kind=small}
- Features
- Tech Stack
- Architecture
- Getting Started
- Environment Variables
- Testing
- Pages
- API Routes
- Multi-Agent System
- Project Structure
- Future Improvements
- Contributing
- License
- 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
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 | |
| Firefox Nightly |
Firefox users: The Web Speech API is disabled by default. To enable it:
- Navigate to
about:configin Firefox. - Search for
media.webspeech.recognition.enableand set it totrue. - 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.
- 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
- 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
- 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
- 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
- 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
- 5 Specialized AI Agents working together:
- Orchestrator → Context → Data → Reasoning → Action
- Transparent Reasoning: See each agent's thought process
- Parallel Processing: Efficient query handling
- 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)
- Clerk Integration: Secure sign-in/sign-up
- User Profiles: Personalized experience
- Webhook Sync: Real-time user data updates
- 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
- 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
- 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.
- Event Tracking: Track searches, venue interactions, agent performance
- Agent Metrics: Monitor AI pipeline execution times
- Search Patterns: Understand user behavior and preferences
- 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
| 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 |
┌─────────────────────────────────────────────────────────────────┐
│ 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 │ │
│ └─────────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
- Node.js 18+
- npm or yarn
- Git
-
Clone the repository
git clone https://github.com/SatyamPandey-07/WorkSphere.git cd WorkSphere -
Install dependencies
npm install
-
Set up environment variables
cp .env.example .env.local # Edit .env.local with your credentials -
Set up the database
# Prisma 7 uses driver adapters - ensure DATABASE_URL is set npx prisma generate npx prisma db pushSee docs/NEON_DATABASE_POOLING.md for full connection string configuration, PgBouncer pooling setup, and migration workflow.
-
Run the development server
npm run dev
-
Open in browser
http://localhost:3000
npm testnpm run test:watchnpm run test:e2e
npm run test:e2e:ui # With UIFor a full guide on writing, running, and debugging Playwright tests, see docs/PLAYWRIGHT_TESTING_GUIDE.md.
- 57 Unit Tests covering:
- API Route Handlers
- React Components
- Utility Functions
- Rate Limiting
- Analytics
Create a .env.local file in the root directory:
# Database (Neon PostgreSQL)
DATABASE_URL="postgresql://user:password@host/database?sslmode=require"
# Clerk Authentication
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 (Groq)
GROQ_API_KEY=gsk_...
# Pexels (for venue photos - free at pexels.com/api)
PEXELS_API_KEY=your_pexels_key_here
# Upstash Redis (for distributed rate limiting)
UPSTASH_REDIS_REST_URL=https://your-upstash-redis-endpoint.upstash.io
UPSTASH_REDIS_REST_TOKEN=your-upstash-redis-tokenYou 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.
| 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) |
| 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 |
| 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 |
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 │
└─────────────────────────────────────────────┘
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
worksphere/
├── prisma/
│ └── schema.prisma # Database schema
├── public/
│ ├── sw.js # Service worker for PWA
│ └── manifest.json # PWA manifest
├── src/
│ ├── __tests__/ # Test files
│ │ ├── api/ # API route tests
│ │ ├── components/ # Component tests
│ │ └── lib/ # Utility tests
│ ├── agents/ # AI Agent implementations
│ │ ├── Orchestrator.tsx # Routes queries to agents
│ │ ├── ContextAgent.tsx # Extracts user intent
│ │ ├── DataAgent.tsx # Fetches venue data
│ │ ├── ReasoningAgent.tsx # Scores and ranks venues
│ │ └── ActionAgent.tsx # Updates UI
│ ├── app/
│ │ ├── api/ # API routes
│ │ │ ├── chat/ # Agent pipeline endpoint
│ │ │ ├── venues/ # Venue CRUD
│ │ │ │ └── enrich/ # OSM + Pexels enrichment
│ │ │ ├── favorites/ # User favorites
│ │ │ └── conversations/ # Chat history
│ │ ├── ai/ # Main app page
│ │ ├── sign-in/ # Auth pages
│ │ ├── sign-up/
│ │ ├── offline/ # Offline fallback
│ │ └── layout.tsx # Root layout
│ ├── components/
│ │ ├── ai-elements/ # Reusable AI UI components
│ │ ├── ui/ # UI components
│ │ ├── EnhancedChatbot.tsx
│ │ ├── Map.tsx
│ │ ├── VenueCard.tsx # Enhanced with photos, amenities
│ │ ├── VenueRatingDialog.tsx
│ │ ├── VenueSubmissionModal.tsx
│ │ └── ErrorBoundary.tsx
│ ├── hooks/
│ │ ├── usePWA.tsx # PWA installation hook
│ │ ├── useRealTime.tsx # Real-time updates hook
│ │ └── useSpeechRecognition.ts # Voice input with browser-support detection
│ ├── lib/
│ │ ├── prisma.ts # Database client
│ │ ├── utils.ts # Utilities
│ │ ├── rateLimit.ts # Rate limiting
│ │ ├── analytics.ts # Event tracking
│ │ ├── validations.ts # Zod schemas
│ │ ├── venues.ts # OSM + Pexels integration (NEW)
│ │ ├── routing.ts # OSRM routing (NEW)
│ │ └── offlineStorage.ts # IndexedDB for PWA
│ ├── tools/ # AI Agent tools
│ └── types/ # TypeScript types
├── e2e/ # Playwright E2E tests
├── jest.config.js # Jest configuration
├── playwright.config.ts # Playwright configuration
└── package.json
- Open the app at
http://localhost:3000 - Allow location access when prompted
- Start chatting with the AI assistant!
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"
- 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
- Sign in with Clerk
- Click heart icon on venue cards to favorite
- Click "Rate" to submit ratings
- Desktop: Click install icon in browser
- Mobile: "Add to Home Screen"
- Push to GitHub
- Connect repository to Vercel
- Add environment variables
- Deploy!
| 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 |
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:
- Fork the repository and create your feature branch (
git checkout -b feature/amazing-feature). - Implement your changes.
- Make sure all pre-commit checks pass (
npm run lint,npx tsc --noEmit, andnpm test). - Commit your changes (
git commit -m 'feat: Add amazing feature') and push to your branch. - Open a Pull Request against the
mainbranch.
This project is licensed under the MIT License.
Satyam Pandey
- GitHub: @SatyamPandey-07
⭐ Star this repo if you find it helpful!
Made with ❤️ by Satyam Pandey