📍 LocShare

Privacy-First Real-Time Location Sharing

LocShare is a simple, elegant, and privacy-focused application that allows you to share your real-time location with friends and family using a simple passkey. No accounts, no tracking, no footprints.

🌐 Live Demo

This app is hosted and live on Render: https://locshare-xj5k.onrender.com/

✨ Key Features

• 🚀 Real-Time Sharing: Powered by WebSockets (Socket.io) for instant location updates across all devices.
• 🛡️ Privacy First:
  • No user accounts or passwords required.
  • No personal data or location history stored.
  • Stop Sharing toggle to instantly hide your location while staying in the room.
  • Ephemeral sessions that disappear when you're done.
• � Smart Pairing:
  • Link & QR Sharing: Effortlessly invite friends via direct links or scannable QR codes.
  • Optional Passkey: Create custom group passkeys or leave it blank to auto-generate a unique 6-character key.
  • Auto-Join: Share links include the session code for instant one-click joining.
• 🗺️ Interactive Maps: High-performance vector maps powered by Mapbox GL JS with support for multiple styles (Streets, Navigation, Dark, Satellite) and a one-click Compass to reset bearing to North.
• 🧭 Smart Navigation: One-tap navigation shortcuts for Google Maps, Apple Maps, and Waze.
• 📏 Distance Tracking: Real-time distance calculation between you and other group members.
• 🏡 Live Addresses: Integrated reverse-geocoding displays the nearest street address for all members.
• 🎨 Personalized Pins: Customize your profile with a range of colors and icons.
• 📊 Server Health Dashboard: Password-protected real-time monitoring of active users and sessions.
• 🌍 Internationalization: Multi-language support for English, Spanish, French, German, Italian, and Portuguese.

🛠️ Technology Stack

Frontend

• React 18 + TypeScript
• Vite for blazing fast builds
• Tailwind CSS + shadcn/ui for premium aesthetics
• Framer Motion for smooth animations
• Zustand for lightweight state management
• Mapbox GL JS for advanced map rendering
• qrcode.react for session QR code generation
• i18next for multi-language support

Backend

• Node.js + Express
• Socket.io for real-time bidirectional communication
• Tailwind-styled Health Dashboard for system monitoring

🚀 Getting Started

Prerequisites

• Node.js (v18 or later)
• npm or pnpm

Installation

1. Clone the repository:

   git clone https://github.com/Panos1221/LocShare.git
   cd group-share

2. Install dependencies:

   npm install

Running the App

To run the full stack, you need to start both the frontend and the backend server.

1. Start the Backend Server

npm run start:server

The server will run on http://localhost:3000. You can view the health dashboard at http://localhost:3000/health.

2. Start the Frontend Development Server

npm run dev

The app will be available at the URL shown in your terminal (usually http://localhost:8080).

🔑 Configuration

LocShare requires a Mapbox Access Token to display maps.

• You will be prompted to enter your token within the app if it's not detected.
• You can get a free token by creating an account at mapbox.com.

🌍 Environment Variables

Create a .env file in the root directory with the following structure:

# Backend Server Configuration
PORT=3000
HEALTH_PASSWORD=your_secure_password_here

# Frontend Configuration (Vite)
# Optional: WebSocket server URL (defaults to localhost:3000 in dev, window.location.origin in prod)
VITE_WS_URL=http://localhost:3000

# Mapbox Access Token (can also be set via localStorage in the app)
VITE_MAPBOX_TOKEN=your_mapbox_token_here

📁 Project Structure

├── src/
│   ├── components/     # UI components (shadcn + custom)
│   │   ├── color/      # Color picker components
│   │   ├── landing/    # Landing page sections
│   │   ├── layout/     # Layout components (Header, Footer, NavLink)
│   │   ├── map/        # Map-related components
│   │   ├── session/    # Session management components
│   │   └── ui/         # shadcn/ui components
│   ├── lib/            # Utilities, stores, and configuration
│   ├── pages/          # Main application views
│   └── hooks/          # Custom React hooks
├── public/             # Static assets
├── server/             # Backend server
│   └── index.js        # Socket.io backend implementation
└── tailwind.config.ts  # Visual theme configuration

📜 License

This project is licensed under the MIT License.

---

Built for privacy and real-time connectivity.