SafeTrek

Real-time group tracking for safe travels and adventures

SafeTrek is a privacy-focused, consent-based location tracking platform designed for group trips, tours, and outdoor adventures. It provides live GPS tracking, interactive maps, and peer-to-peer navigation in a secure, temporary session model.

Problem Statement

During group excursions (hiking, city tours, family trips), participants frequently get separated. Existing solutions like generic maps or messaging apps don't provide continuous spatial awareness or dedicated trip management, leaving groups fragmented and unsafe.

Solution

SafeTrek creates temporary, secure "Trip" sessions where location sharing is explicit, time-bound, and consent-based. Members join via QR codes, see each other on a live map, and can navigate directly to any group member.

Key Features

• Secure Trip Management: Create trips, invite members via QR codes
• Real-Time GPS Tracking: WebSocket-powered live location updates
• Interactive Map: Clustering, navigation, auto-centering
• Peer-to-Peer Navigation: Calculate distance/bearing to any member
• Privacy-First: Extended identity data (passport, blood group) stored but never publicly exposed
• Multi-Language: Full English/Arabic support with RTL layout
• Dark Mode: System-aware light/dark themes
• Demo Mode: Simulated users for testing without multiple devices
• Trip History: Archive of completed trips for all participants

Tech Stack

Backend

• FastAPI (Python) - High-performance async web framework
• PostgreSQL - Relational database with spatial readiness
• SQLAlchemy - ORM with Alembic migrations
• Socket.IO - WebSocket communication for real-time updates
• JWT - Secure authentication

Frontend

• React + Vite - Modern, fast build tooling
• Leaflet - Open-source interactive maps
• Tailwind CSS - Utility-first styling
• i18next - Internationalization (EN/AR)
• React Context - Global state management

Architecture Highlights

• Event-Driven Real-Time: WebSocket rooms ensure location broadcasts are scoped to trip participants only
• Mobile-First Design: Touch-optimized UI, responsive layouts
• Consent-Based Model: No "search for user" feature; join only via QR code proximity
• Ephemeral Tracking: Location data is relevant only during active trips

Getting Started

Prerequisites

• Python 3.9+
• Node.js 18+
• PostgreSQL 14+

Installation

1. Clone the Repository

git clone <repository-url>
cd "HACK PI NIGHT"

2. Backend Setup

cd backend

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Configure environment
cp .env.example .env
# Edit .env with your PostgreSQL credentials

# Run migrations
alembic upgrade head

# Start server
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

3. Frontend Setup

cd frontend

# Install dependencies
npm install

# Start development server
npm run dev -- --host 0.0.0.0

Network Configuration (Mobile Testing)

To test on your mobile device, you need to configure the project with your computer's local IP address.

Option 1: Automatic Setup (Recommended)

We have provided scripts to automatically update the IP address and start the servers.

1. Find your local IP address:

   # Windows
   ipconfig
   # Look for IPv4 Address (e.g., 192.168.1.50)

2. Run the setup script:

   Windows:

   run.bat 192.168.1.50

   Linux/Mac:

   chmod +x run.sh
   ./run.sh 192.168.1.50

   This will:

   • Update the IP address in all necessary files (backend.js, WebSocketContext.jsx, main.py)
   • Start the Backend server
   • Start the Frontend server

Option 2: Manual Setup

1. Update configuration files manually with your IP:

   • frontend/src/api/backend.js - Update API_BASE
   • frontend/src/context/WebSocketContext.jsx - Update wsUrl
   • backend/app/main.py - Update CORS origins

2. Start servers manually: See "Development Workflow" below.

Current IP: 192.168.182.127

Chrome Flags for HTTP Testing

Since GPS and Camera require HTTPS in production, enable these flags in Chrome for local testing:

chrome://flags/#unsafely-treat-insecure-origin-as-secure

Add: http://<YOUR_IP>:5173 (e.g., http://192.168.182.127:5173)

Project Structure

.
├── backend/
│   ├── alembic/              # Database migrations
│   ├── app/
│   │   ├── api/              # Route handlers
│   │   ├── models/           # SQLAlchemy models
│   │   ├── schemas/          # Pydantic schemas
│   │   ├── core/             # Auth, database, security
│   │   └── main.py           # FastAPI app entry
│   └── requirements.txt
├── frontend/
│   ├── src/
│   │   ├── api/              # Backend API client
│   │   ├── components/       # Reusable UI components
│   │   ├── context/          # React Context providers
│   │   ├── pages/            # Page components
│   │   ├── locales/          # i18n translations
│   │   └── utils/            # Helper functions
│   ├── package.json
│   └── vite.config.js
└── docs/
    ├── project_report.md     # Technical deep-dive
    └── mobile_testing_guide.md

API Documentation

Once the backend is running, access interactive API docs:

• Swagger UI: http://192.168.182.127:8000/docs
• ReDoc: http://192.168.182.127:8000/redoc

Database Schema

Core Tables

• users: Authentication, profile, identity data
• trips: Trip metadata (name, owner, timestamps)
• trip_members: Many-to-many relationship with location tracking
• trip_invites: QR-based invitation management

Development Workflow

1. Start Backend: Terminal 1

   cd backend
   uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

2. Start Frontend: Terminal 2

   cd frontend
   npm run dev -- --host 0.0.0.0

3. Database Migrations: When models change

   cd backend
   alembic revision --autogenerate -m "Description"
   alembic upgrade head

Demo Mode

To test without multiple devices:

1. Login to the app
2. Navigate to Dashboard
3. Look for "Demo Mode" toggle
4. View a simulated trip with 5 moving users

Security Considerations

• JWT Authentication: Secure token-based auth
• Password Hashing: bcrypt with salt
• CORS: Restricted to trusted origins
• QR Signatures: Cryptographically signed to prevent spoofing
• Private Data: Extended profile fields (passport, blood group) never exposed in public APIs

📸 Project Gallery

Future Enhancements

• Push notifications for trip invites
• Offline map caching
• Trip geofencing with alerts
• Emergency SOS broadcast
• Integration with weather APIs

Contributing

This project was developed for a hackathon. Contributions are welcome:

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Open a pull request

Acknowledgments

• OpenStreetMap for map tiles
• Leaflet for map rendering
• FastAPI community for excellent documentation

---

Built with ❤️ for safer group travel