---

👑 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 automated CI pipeline will automatically approve and squash-merge your PR with co-author credit!

---

🚀 Contributors (126 Active Rockstars)

A massive thank you to all 126 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	shrinivas-sn
reyhaan07	saisarans2007	harichillin	CoderSoham345	kiranShamsHere	Rohan766-negi	Khushi-agarwal1401
kailash71869-code	bhavesh-patil2007	IsmeetPandey	saurabhwagh01	KartikManral092006	radheshyam-bhati	mohanapriya9324

---

📋 Table of Contents

• Features
  • AI & Search Intelligence
  • Web3, Solana Pay & Smart Escrow
  • Edge Audio & Acoustic Privacy (WASM DSP)
  • Spatial Computing, WebXR & Ergonomics
  • Digital Twin & Building IoT Orchestration
  • Decentralized Networking & Survival Mesh
  • Nomad Travel, Housing & War Rooms
  • Zero-Knowledge Proofs & Security
• Core Platform Capabilities
• Tech Stack
• Architecture
• Getting Started
• Environment Variables
• Testing
• Pages
• API Routes
• Multi-Agent System
• Project Structure
• Troubleshooting
• Future Improvements
• Contributing
• License

---

✨ Features

🤖 AI-Powered Search

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

🎙️ Voice Input (Browser Support)

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

Browser	Voice Input
Chrome 33+	✅ Supported
Edge 79+	✅ Supported
Safari (desktop/mobile)	✅ Supported (webkit prefix)
Firefox Stable	⚠️ Not supported by default
Firefox Nightly	⚠️ Requires flag — see below

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

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

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

🗺️ Interactive Dark Theme Map

• Dark Theme: Beautiful CartoDB Dark Matter tiles
• Real-time Markers: Purple glowing venue markers with venue photos
• PostGIS Geospatial Proximity Search & GiST Indexing: Accelerated KNN nearest-neighbor query for nomad venues within radius bounds using PostgreSQL native PostGIS ST_DWithin spherical calculations without in-memory Haversine compute overhead (/api/venues/search, src/lib/search/spatialVenueSearch.ts).
• 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
• Interactive Noise Decibel Slider Filter: Real-time acoustic slider and preset buttons allowing users to filter coworking venues by ambient decibel thresholds (30 dB - 100 dB) across quiet study zones and collaborative spaces (src/components/venues/NoiseLevelSlider.tsx).
• One-Click Filter Reset & ARIA-Live Announcements: One-click "Clear all" filter button with accessible screen-reader count announcements rendered inside an aria-live="polite" region (src/components/venues/VenueFilterBar.tsx).
• 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
• Case-Insensitive Normalized Email & Magic Link Auth: Resilient authentication flow featuring RFC-compliant email normalization via Zod schemas, whitespace trimming, and fail-safe magic link token issuance (src/lib/auth/emailService.ts).
• JWT Refresh Token Invalidation on Password Change: Tracks passwordChangedAt in the User model to immediately invalidate previously issued refresh tokens upon credential rotation (src/lib/auth/emailService.ts, prisma/schema.prisma).
• 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
• Visual Loading States: Accessible loading indicators and animated spinner feedback while rendering cryptographically verified booking receipts (src/components/receipt/ReceiptVerificationModal.tsx).
• 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

• PostgreSQL Concurrency Serialization with NOWAIT Advisory Locks: High-throughput seat reservation serialization using transaction-level advisory locks with immediate non-blocking failure semantics (NOWAIT), eliminating split-second double-booking races under intense demand spikes (src/app/api/reservations/book/route.ts).
• OpenTelemetry W3C Distributed Tracing: Distributed context propagation utilizing standard W3C traceparent and tracestate headers across microservices with sub-operation span instrumentation (src/lib/telemetry/tracer.ts, src/middleware.ts).
• Backpressure-Aware SSE AI Streaming: Implements stream throttling respecting client backpressure via controller.desiredSize and handles immediate disconnection cleanup via AbortSignal (src/app/api/ai/stream/route.ts).
• Adaptive Bitrate (ABR) WebRTC AIMD Controller: Dynamically regulates WebRTC video and screen share bitrates based on peer connection getStats loss, RTT, and bandwidth metrics using Additive Increase Multiplicative Decrease (src/lib/webrtc/abrController.ts).
• Probabilistic Vector Cache Stampede Prevention (XFetch): Implements the optimal XFetch algorithm for vector embeddings during hybrid semantic venue searches, computing early background re-fetches as expiration nears to completely prevent thundering-herd cache stampedes (src/lib/search/hybridSearch.ts).
• Idempotent Venue Reviews & Deduplication Engine: Robust header-based idempotency layer (x-idempotency-key) utilizing SHA-256 payload hashing, concurrent in-flight promise memoization, and conflict detection returning 409 Conflict on key reuse with altered payloads (src/lib/idempotency.ts, src/app/api/venues/[venueId]/reviews/route.ts).
• Distributed Redlock Monotonic Fencing Tokens: Concurrency control across distributed multi-instance Redis clusters preventing split-brain double desk bookings with monotonically increasing lease fencing tokens (src/lib/redis/RedlockManager.ts).
• Rate Limiting: API protection with configurable limits
• Security Architecture: CSP nonces, signed double-submit CSRF cookies and multi-tier token bucket rate limiting, explained end to end in docs/security/SECURITY_OVERVIEW.md
• 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).
• Solana Optimistic Escrow Simulation: Pre-flight RPC simulation with balance delta verification, transaction build pipeline, and fallback reconciliation for zero-latency desk escrow holds (src/lib/solana/escrowClient.ts).
• Solana Escrow Cluster RPC Failover Pool: Resilient multi-endpoint RPC cluster failover with automated health probes, exponential jitter backoff, and optimistic client simulation for instant desk escrow deposits (/api/pay/solana, /api/cron/escrow-refund, src/lib/solana/escrowClient.ts).
• 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

• Accessible Venue Grid Tooltips & Keyboard Shortcuts: Full WCAG-compliant keyboard navigation (G for Grid, C for Compact, M for Map) with animated tooltip overlays and focus ring management (src/components/ui/VenueGrid.tsx).
• Ergonomic Posture Audio Coach & Dynamic Mute Controls: Integrated audio coaching engine providing real-time ergonomics nudges with accessible mute toggles and persistent user preference state (src/components/venue/VenueCard.tsx, /wellness/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).
• W3C WebRTC Perfect Negotiation & Glare Rollback: Symmetric polite/impolite role negotiation engine resolving concurrent offer collisions and ICE candidate race conditions across collaborative nomad audio/video meshes (src/core/network/WebRTCMesh.ts).
• 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

• CRDT State Vector Exchange & Differential Compaction Protocol: Ultra-low-bandwidth collaborative whiteboard synchronization utilizing Yjs state vector exchanges, incremental update compaction, and differential snapshot pruning (docs/crdt/CRDT_VECTOR_COMPACTION.md).
• IndexedDB CRDT Offline Change-Journal Replay Buffer: Resilient append-only transaction journal capturing serialized Y.encodeStateAsUpdate frames during intermittent nomad connectivity, providing topological re-streaming and seamless state reconciliation upon reconnect (src/lib/crdt/canvasProvider.ts).
• 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

• ZK-SNARK Coworking Membership Verifier: Circom-compiled Groth16 zero-knowledge circuit for proving coworking membership passes and access tiers without disclosing nomad identity (/api/zkp/membership/verify, circuits/membership_verifier.circom).
• 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).
• PostgreSQL Persistent ZKP Nullifier Table: Enforces database-level replay protection with transactional ON CONFLICT DO NOTHING on zero-knowledge spent nullifiers, preventing double-spending during anonymous check-ins (src/lib/crypto/zkNullifierVerifier.ts).
• Atomic Redis Sliding-Window Rate Limiter: High-concurrency protection using atomic Lua scripts preventing burst bypasses across API routes (/api/v1/*).

---

🌟 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          │                      │
│  └─────────────────┘  └─────────────────┘                      │
└─────────────────────────────────────────────────────────────────┘

Architecture Deep Dives

• Redlock Lease Fencing Token Protocol: how fencing tokens are generated, renewed and checked at the reservation transaction boundary, with failover and lease-renewal sequence diagrams.
• Architecture documentation index

---

🚀 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

1. Clone the repository

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

2. Install dependencies

   npm install
   

3. Choose your environment setup path:

   Option A: Docker Compose (Recommended)

   This starts a local PostgreSQL instance (with the pgvector extension) and Redis automatically. See docs/guides/LOCAL_DEVELOPMENT_SETUP.md for full container architecture and configuration options.

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

   Option B: Manual Setup

   If you prefer not to use Docker:

   1. Setup a PostgreSQL 15+ database with the pgvector extension enabled.
   2. Optionally setup an Upstash Redis database.
   3. Copy environment config and fill in Neon and Upstash URLs:

      cp .env.example .env.local
      

4. Initialize Database Schema

   npx prisma generate
   npx prisma db push
   

5. Run the development server

   npm run dev
   

6. Open in browser

   http://localhost:3000
   

---

🔧 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

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

Feature Testing Checklist

🔍 AI Search

Try these natural language queries:

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

🎙️ Voice Input

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

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

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

⭐ Favorites & Ratings (Requires Sign-in)

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

📱 PWA Installation

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

---

🚀 Deployment

Deploy to Vercel

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

---

🔮 Future Improvements

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

---

🤝 Contributing & Issue Workflow

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

⚡ Automated Issue Assignment

1. Find an Issue: Explore our Open Issues.
2. 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.
3. Release with /unclaim: If you need to step away from an issue, simply comment /unclaim to release it for other contributors.
4. 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

---