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 (111) • 🐛 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 (111 Active Rockstars)

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

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

✨ 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

838+ Test Suites: Full coverage with Jest & React Testing Library
E2E Testing: Playwright configuration for end-to-end user journey tests
API Tests: Route handler testing with in-memory request simulation
Component Tests: UI component validation and accessibility audits

💸 Web3, Solana Pay & Smart Escrow

Solana Pay Engine: High-contrast QR payment modal with dynamic payment request generation, Screen Wake Lock API integration to prevent display dimming during scan, and verifiable on-chain confirmation (protected against synthetic confirmation spoofing).
Focus Session Bounties & Escrow: Stake crypto tokens to commit to deep work sessions; automated smart-contract payout release upon verified session completion (/api/bounties/payout, /api/bookings/escrow).
Virtual Single-Use Cards & Automated Invoicing: Issue ephemeral corporate cards for workspace booking expenses with automatic OCR receipt reconciliation (/api/finance/card).
Nomad Tax Residency Geo-Fence & ZK Ledger: Automated tracking of border crossings and physical presence duration with zero-knowledge cryptographic proof generation (/analytics/nomad-tax).
JSON & CSV Tax Export: Download complete tax records, workspace rental deductions, and business expense summaries formatted for international digital nomad audits (/api/bookings/export).

🎧 Edge Audio Processing & Acoustic Privacy (WASM DSP)

Dynamic Acoustic Privacy Jammer: WebAssembly DSP ring buffer applying Delayed Auditory Feedback (DAF) to headphones, scientifically disrupting loud speech and maintaining private conversations in open cafes (/api/audio/jammer).
AI Generative Venue Vibe Audio Synthesizer: Procedural acoustic soundscapes and focus-frequency noise generation tailored in real-time to current venue ambient noise telemetry (/api/audio/vibe).
Spatial RT60 Reverberation Analyzer: In-browser acoustic impulse measurement calculating venue echo decay time (RT60) to grade conference call suitability (/api/venues/acoustics/rt60).
Keyboard Acoustic Emanation Shield: Client-side acoustic masking preventing microphone-based keystroke eavesdropping in public coworking lounges (/api/security/acoustic).

👓 Spatial Computing, WebXR & Ergonomics

WebXR SLAM Venue Scanner & Voxel Octree: Camera-based spatial mapping for desk geometry, power outlet coordinates, and indoor navigation paths (/ar/finder).
Real-Time 3D Desk Ergonomics & ISO Validator: WebGL 3D avatar posture analysis evaluating chair height, screen angle, and ambient lighting against ISO 9241 standards (/wellness/ergonomics).
Automated Audio-Description Spatial Scene Graph: Real-time accessibility engine converting venue visual layout into navigable spatial audio narration for visually impaired professionals (/api/accessibility/scene).
Team Proximity Haptic Feedback & Spatial Anchoring: Physical team proximity alerts using Gamepad/Web Haptics API and spatial beacon tags (/api/ar/anchors).

🏢 Digital Twin & Building IoT Orchestration

Workspace Digital Twin HVAC & Air Quality Purge: Live CO2, TVOC, and PM2.5 monitoring triggering automated ventilation requests and threshold breach alerts (/api/twin/airquality).
Cafe Power Grid Load Forecasting & Breaker Trip Predictor: Wattage monitoring preventing sudden cafe circuit breaker trips (/venues/power-grid).
Multi-Sensory Focus Environment IoT Controller: Smart lighting (circadian CCT), desk height, and acoustic masking control via Matter / HomeKit / Zigbee bridges (/api/iot/orchestrate).
ASHRAE Standard 55 Thermal Comfort Index: Predicted Mean Vote (PMV) and Predicted Percentage Dissatisfied (PPD) computed live from ambient temperature and relative humidity sensors.

🌐 Decentralized Networking & Survival Mesh

Distributed Compute-Burst WebRTC Mesh: Collaborative local distributed computing offloading code builds and heavy processing across idle laptops on cafe WiFi (/p2p/mesh-collab, /api/compute/burst).
Offline-First P2P Emergency Mesh Network: WebRTC DataChannels + Bluetooth Low Energy (BLE) peer discovery maintaining critical comms during cafe ISP outages (/api/network/survival).
Offline Medical Emergency Mesh Beacon & First-Aid Router: Instant SOS broadcasting and automated navigation to the nearest automated external defibrillator (AED) and medical kit (/api/medical/beacon).
Bandwidth-Hog Identification & Cooperative QoS: Local network cooperative monitoring to detect and throttle background stream hogs on public WiFi (/api/network/qos).

✈️ Nomad Travel, Smart Housing & Collab War Rooms

Flight-Delay Itinerary Auto-Rerouting: Webhook integration with aviation feeds automatically rescheduling booked coworking passes when flights are delayed or cancelled (/api/travel/reroute).
Git Merge Conflict Physical War Room & IoT Lockdown: Automatic physical meeting room booking and IoT access lockdown during critical deployment conflicts (/api/collab/warroom).
Decentralized Nomad Housing Swap & Smart-Contract Lease Ledger: Peer-to-peer apartment and studio exchange protocol backed by decentralized identity and reputation scores (/api/housing/swap).
Distributed Luggage Storage P2P Trust & IoT Locker Protocol: Secure short-term storage locker management with cryptographic token keys and BLE unlock (/peripherals/locker, /api/luggage/store).
Micro-Climate Pedestrian Routing & Wind-Tunnel Risk Engine: OSRM routing enriched with real-time micrometeorology, sheltering laptops from rain squalls and wind tunnels (/api/routing/microclimate).
Predictive Cafe Inventory Restocking Engine: Real-time oat milk, specialty bean, and pastry stock forecasting based on check-in velocity (/venues/cafe-order, /api/inventory/restock).

🛡️ Zero-Knowledge Proofs, Security & Compliance

Decentralized DID Wallet & ZK-Age / Identity Verification: Verify KYC and identity requirements without disclosing personal identity documents (/test-student-zkp, /api/identity/verify).
Client-Side PII Redaction & Document Sanitization Pipeline: In-browser regex and NER model scrubbing sensitive credentials, emails, and phone numbers before cloud transmission (/api/documents/sanitize).
AI-Powered Legal & NDA Redline Assistant: In-browser automated contract analysis, clause risk scoring, and interactive redlining before booking commercial spaces (/api/legal/redline).
Cryptographic Proof-of-Deep-Work Ledger with ZK-SNARKs: Verifiable proof of undistracted deep-work time for client billing without surveillance (/api/zkp/deepwork).
ECDH P-256 + AES-GCM 256 End-to-End Encrypted (E2EE) Chat & SPKI Key Pinning: Zero-knowledge team communication with SPKI SHA-256 Certificate Public Key Pinning (/api/auth/passkey/*).
Audit Log SHA-256 Merkle Tree Verification: Tamper-evident immutable audit log endpoint (/api/admin/audit/verify).

🌟 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.
💳 Solana Pay & Smart Escrow	One-click crypto micro-payments, QR scan with Wake Lock, and deep-work bounty escrow payouts.	Real-time Solana RPC verification, anti-spoofing transaction filters, smart contract escrow.
🎧 WASM DSP Acoustic Privacy	Speech jamming with Delayed Auditory Feedback (DAF) preventing loud calls in public cafes.	WebAudio AudioWorklet + WebAssembly C ring buffer for ultra-low latency audio processing.
👓 WebXR SLAM Spatial Scanner	Augmented Reality indoor desk finder, power outlet locator, and millimeter-level wayfinding.	WebXR Device API, point cloud voxelization, and SLAM visual-inertial odometry.
🏢 Digital Twin HVAC & Air Purge	Automated indoor environmental air quality purge alerts and smart ventilation orchestration.	Real-time CO2/PM2.5 IoT telemetry with threshold anomaly detection and BACnet/MQTT bridge.
🌐 Distributed WebRTC Compute Mesh	Offload heavy compile and test workloads onto idle peer machines connected to the same cafe WiFi.	WebRTC DataChannels, P2P work stealing algorithm, and distributed task chunking.
🔋 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 Survival PWA	Browse cached venues, floor plans, and queue check-ins completely offline via mesh networking.	Service Worker background sync + IndexedDB storage + Web Locks API synchronization.
🧾 Cryptographic PDF Invoicing	Instant one-click PDF receipts with HMAC-SHA256 signatures generated for verified bookings.	100% serverless, zero-filesystem execution via `pdf-lib` with embedded Helvetica glyphs.
🎓 Zero-Knowledge Identity & Perks	Claim verified student discounts and KYC clearance without revealing personal identification documents.	Client-side WASM ZKP proof generation with offline localStorage verification caching.
✈️ Flight Reroute & IoT War Room	Auto-reschedule bookings upon flight delays and lock down physical war rooms on merge conflicts.	Aviation webhook feeds, automated calendar rebalancing, and IoT smart-lock triggers.
🛡️ Edge PII Redaction & E2EE	Client-side redaction of sensitive credentials and documents before leaving the local browser.	Zero-knowledge ECDH P-256 + AES-GCM 256 encryption with SPKI SHA-256 public key pinning.

🛠️ Tech Stack

Category	Technology
Framework	Next.js 15.5 (App Router with Server Components & Server Actions)
Language	TypeScript 5.0
Styling	Tailwind CSS 4.0, Radix UI Primitives, Lucide Icons
AI / Multi-Agent	Groq SDK (Llama 3.3 70B Versatile), In-Browser Intent Orchestrator
Database	Neon Serverless PostgreSQL + Prisma 7.2 ORM (with `@prisma/adapter-pg`)
Authentication	Clerk (JWTs, Webhook Sync, Passkeys & WebAuthn)
Web3 & FinTech	Solana Web3.js, Solana Pay Protocol, Smart Contract Escrows
Edge Audio / DSP	WebAssembly (WASM C DSP), AudioWorklet API, Web Audio Oscillators
Spatial & AR	WebXR Device API, Three.js / WebGL, Voxel Octrees
Maps & Routing	React Leaflet, OpenStreetMap, OSRM Road Machine, CartoDB Dark Matter
Real-time & P2P	PartyKit WebSockets, Server-Sent Events (SSE), WebRTC DataChannels
Digital Twin / IoT	Matter / HomeKit Bridge, MQTT Telemetry, Web Bluetooth Low Energy (BLE)
Cryptography / ZKP	Web Crypto API (SubtleCrypto HMAC-SHA256), WASM ZK-SNARKs (SnarkJS)
PDF Generation	pdf-lib 2.x (Zero-filesystem serverless execution)
Testing	Jest 29, React Testing Library, Playwright E2E (838+ test suites)
PWA & Offline	Service Workers, IndexedDB, Background Sync API, Web Locks API
Deployment	Vercel (Edge & Serverless Functions)

🏗️ 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 20+ (Node.js 20 LTS or Node.js 22 LTS recommended)
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
```

🔧 Troubleshooting

New contributors commonly run into a few setup hurdles when configuring their local environment. Here are the most frequent issues and their quick fixes:

1. `PrismaClientInitializationError` / Database Connection Failures

Symptom:

PrismaClientInitializationError: Can't reach database server at `localhost:5432`
Please make sure your database server is running at `localhost:5432`.

or

The table `public.Venue` does not exist in the current database.

Root Causes & Solutions:

Container not started: If using Docker Compose, ensure the PostgreSQL and Redis containers are actively running:
```
docker compose ps
docker compose up -d
```
Prisma Schema not pushed: If the database exists but tables or columns are missing, synchronize the schema:
```
npx prisma generate
npx prisma db push
```
Seeding sample data: To populate local venues and amenities:
```
npm run postinstall
node prisma/seed.js
```

2. Node.js Engine & Dependency Incompatibilities

Symptom:

error: Unsupported engine. The engine "node" is incompatible with this module.
Expected version ">=20.0.0". Got "v18.19.0".

or syntax errors involving modern TypeScript experimental strip types, ECMAScript modules, or WebAssembly SIMD loaders.

Root Causes & Solutions:

WorkSphere leverages Node.js 20+ runtime features (experimental type stripping, native fetch optimizations, and ES2024 features).
Check your current Node.js version:
```
node -v
```
If your version is lower than v20.0.0, update via nvm (macOS/Linux) or nvm-windows:
```
# Install and switch to Node.js 20 or 22 LTS
nvm install 20
nvm use 20
```

3. Stale Next.js Build Cache (`.next`)

Symptom:

Error: Cannot find module 'next/dist/server/...'

or hydration mismatch errors, stale chunk load errors, or webpack compilation failures after pulling major upstream changes.

Root Causes & Solutions:

Next.js caches compiled pages and webpack artifacts in .next/. When branch switching or updating dependencies, the cache can become invalid.
Clear the Next.js build cache and reinstall dependencies cleanly:

On macOS / Linux / Git Bash:
```
rm -rf .next
npm run dev
```
On Windows PowerShell:
```
Remove-Item -Recurse -Force .next
npm run dev
```

If you encounter native module mismatches:

# Deep clean
rm -rf .next node_modules package-lock.json
npm install
npx prisma generate
npm run dev

4. Missing or Unconfigured Environment Variables (`.env.local`)

Symptom:

Error: Missing environment variable: DATABASE_URL

or authentication redirection loops with Clerk, or map tile loading failures.

Root Causes & Solutions:

Next.js requires .env.local for local secrets. Ensure you copied .env.example:
```
cp .env.example .env.local
```

Verify the following essential keys in .env.local:

# Local Docker Postgres (default)
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/worksphere?schema=public"
DIRECT_URL="postgresql://postgres:postgres@localhost:5432/worksphere?schema=public"

# Upstash Redis (Optional for rate limiting; mock fallback exists)
UPSTASH_REDIS_REST_URL="http://localhost:8079"
UPSTASH_REDIS_REST_TOKEN="example_token"

# App Base URL
NEXT_PUBLIC_APP_URL="http://localhost:3000"

Restart npm run dev after updating .env.local to allow Next.js to reload environment variables.

🧪 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 (52 Interactive Application Views)

Category	Route	Page	Description
Core AI & Maps	`/`	Landing Page	Hero section with product showcase, community stats, and CTAs
	`/ai`	AI Workspace Finder	Dual-pane 70/30 interactive CartoDB map & multi-agent reasoning chat
	`/ai/concierge`	AI Concierge	Natural-language concierge for itinerary planning & seat reservations
	`/workspace`	Workspace Suite	Multi-window workspace manager with persistent layout state
	`/compare`	Venue Comparison	Side-by-side metric matrix comparison across multiple venues
Social & Collaboration	`/social`	Nomad Community Hub	Local digital nomad community feeds, check-ins, and networking
	`/social/focus-room`	Virtual Focus Rooms	Collaborative Pomodoro sessions with synchronized willpower gauges
	`/social/meet-halfway`	Meet Halfway Engine	Geospatial midpoint calculator for distributed team meetings
	`/social/skill-exchange`	Skill Barter Hub	Web-of-trust peer-to-peer knowledge and skill exchange
	`/bundles/work-hop`	Work-Hop Pass	Multi-venue pass bundle purchasing and check-in scanner
Web3 & FinTech	`/pay/crypto-micro`	Solana Pay Portal	Dynamic QR-code crypto micropayment terminal with Wake Lock
	`/pay/split/[token]`	Bill Splitting Hub	Multi-party workspace booking bill split and settlement
	`/peripherals/locker`	Smart IoT Locker Grid	Decentralized luggage & equipment locker rental protocol
Spatial & Hardware	`/ar/finder`	WebXR AR Wayfinding	Augmented Reality SLAM indoor desk & outlet finder
	`/wellness/ergonomics`	3D Desk Ergonomics	Real-time WebGL 3D avatar posture analysis & ISO 9241 evaluation
	`/venues/sound-gradient`	Acoustic Heatmap	Real-time spatial sound level gradient and noise contour map
	`/venues/power-grid`	Power Grid Monitor	Real-time cafe electrical load forecasting & breaker trip alert
	`/venues/solar-finder`	Solar Glare & Sun Calc	Solar angle & natural daylight tracking for glare-free outdoor desks
Analytics & Nomad Compliance	`/analytics`	Telemetry Dashboard	Venue network latency, noise history, and occupancy analytics
	`/analytics/nomad-tax`	Nomad Tax & Border Ledger	Zero-knowledge border crossing ledger and tax residency tracker
	`/analytics/carbon`	Carbon Footprint Tracker	Commute and workspace energy consumption offset calculator
	`/analytics/noise-forecasting`	Predictive Noise Engine	Prophet-based forecasting for future crowd and decibel levels
User & Administration	`/dashboard`	User Neural Ledger	Personal dashboard, confirmed bookings, and cryptographic receipts
	`/dashboard/webhooks`	Webhook Integrations	Developer webhook endpoint management and event delivery logs
	`/user-profile/passport`	Nomad Digital Passport	Verifiable credential badges, check-in history, and POAPs
	`/admin/system`	Admin System Diagnostics	Partition maintenance, DB health, and memory telemetry
	`/admin/performance`	Core Web Vitals Monitor	Real-time server latency, TTFB, and route latency heatmaps
	`/offline`	Offline Survival Mode	Offline-first PWA fallback with cached venues and queue sync
	`/sign-in`	Sign In	Clerk authentication sign-in portal
	`/sign-up`	Sign Up	Clerk authentication sign-up portal

🔌 API Routes (300+ Modular Endpoints)

WorkSphere features a modular API architecture organized across specialized subsystems:

Subsystem	Key Endpoints	Description
🤖 Multi-Agent AI	`/api/chat` `/api/ai/concierge` `/api/legal/redline` `/api/scheduling/pod`	Multi-agent reasoning pipeline, legal NDA redlining, and meeting pod optimization
🎧 WASM Audio & DSP	`/api/audio/jammer` `/api/audio/vibe` `/api/venues/acoustics/rt60` `/api/security/acoustic`	DAF speech jamming, AI ambient soundscapes, RT60 spatial acoustics, and acoustic masking
💳 Web3 & Payments	`/api/payments/solana/*` `/api/bounties/payout` `/api/bookings/escrow` `/api/finance/card`	Solana Pay RPC verification, focus bounties escrow, and virtual card issuance
👓 Spatial & WebXR	`/api/venues/slam` `/api/ar/anchors` `/api/accessibility/scene` `/api/spatial/beacons`	SLAM voxel octree, AR anchors, audio-described spatial scene graphs, and team proximity
🏢 Digital Twin & IoT	`/api/twin/airquality` `/api/venues/powergrid` `/api/iot/orchestrate` `/api/wellness/ergonomics`	HVAC air purge orchestrator, cafe breaker trip prediction, Matter IoT bridges, and ergonomics
🌐 Mesh & Survival	`/api/compute/burst` `/api/network/survival` `/api/medical/beacon` `/api/network/qos`	WebRTC distributed compute mesh, offline P2P emergency network, and medical beacon
🛡️ ZKP & Security	`/api/auth/zkp/nomad-proof` `/api/identity/verify` `/api/documents/sanitize` `/api/zkp/deepwork`	Zero-knowledge identity proofs, client-side PII sanitization, and proof-of-deep-work
🗺️ Venues & Routing	`/api/venues` `/api/venues/enrich` `/api/routing/microclimate` `/api/travel/reroute`	Venue search & OSM enrichment, micro-climate weather routing, and flight-delay rerouting
🧾 Bookings & Receipts	`/api/bookings` `/api/bookings/[id]/download` `/api/tax/nomad-compliance` `/api/bookings/export`	Serverless PDF receipt generation with HMAC-SHA256 signatures and JSON/CSV tax exports
📊 Admin & Diagnostics	`/api/admin/audit/verify` `/api/admin/performance` `/api/admin/system/latency-heatmap`	SHA-256 Merkle tree verification, route latency canvas heatmaps, and system diagnostics

🤖 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.check.json		tsconfig.check.json
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation

WorkSphere

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

👑 Project Leadership & Authorship

🚀 Contributors (111 Active Rockstars)

📋 Table of Contents

✨ Features

🤖 AI-Powered Search

🎙️ Voice Input (Browser Support)

🗺️ Interactive Dark Theme Map

📡 Real-time Venue Updates (NEW)

📸 Venue Photos (NEW)

🏢 Venue Enrichment (100% FREE APIs)

🛣️ Real Road Routing

🎯 Multi-Agent Architecture

⭐ User Features

🔐 Authentication

🧾 PDF Receipt System

📱 Progressive Web App (PWA)

🚀 Performance & Reliability

📊 Analytics & Monitoring

🧪 Comprehensive Testing

💸 Web3, Solana Pay & Smart Escrow

🎧 Edge Audio Processing & Acoustic Privacy (WASM DSP)

👓 Spatial Computing, WebXR & Ergonomics

🏢 Digital Twin & Building IoT Orchestration

🌐 Decentralized Networking & Survival Mesh

✈️ Nomad Travel, Smart Housing & Collab War Rooms

🛡️ Zero-Knowledge Proofs, Security & Compliance

🌟 Core Platform Capabilities

🛠️ Tech Stack

🏗️ Architecture

🚀 Getting Started

Prerequisites

Installation & Setup

Option A: Docker Compose (Recommended)

Option B: Manual Setup

🔧 Troubleshooting

1. PrismaClientInitializationError / Database Connection Failures

2. Node.js Engine & Dependency Incompatibilities

3. Stale Next.js Build Cache (.next)

4. Missing or Unconfigured Environment Variables (.env.local)

🧪 Testing

Run All Tests

Watch Mode

End-to-End Tests

Test Coverage

🔐 Environment Variables

Getting API Keys

📱 Pages (52 Interactive Application Views)

🔌 API Routes (300+ Modular Endpoints)

🤖 Multi-Agent System

Agent Pipeline Flow

Agent Transparency

📁 Project Structure

Key directories at a glance

🧪 Testing the App (User Guide)

Quick Start Test

Feature Testing Checklist

🔍 AI Search

🎙️ Voice Input

⭐ Favorites & Ratings (Requires Sign-in)

📱 PWA Installation

🚀 Deployment

Deploy to Vercel

🔮 Future Improvements

🤝 Contributing & Issue Workflow

⚡ Automated Issue Assignment

📄 License

👨‍💻 Author

About

Topics

Resources

Code of conduct

Contributing

Security policy

Accessibility

1. `PrismaClientInitializationError` / Database Connection Failures

3. Stale Next.js Build Cache (`.next`)

4. Missing or Unconfigured Environment Variables (`.env.local`)