Friend Compass

What is it?

Friend Compass is a web application that lets users share location in real-time with others. It provides a simple interface to see where everyone is relative to themselves, and does not require any accounts or authentication. Just share the room link or QR code, and everyone can join and see each other's location on a map.

Features

• Real-time location sharing with multiple friends
• No authentication required, just share the room link or QR code to join
• No app to install, works on mobile browsers with geolocation support
• Relative location markers on a map showing direction and distance to each friend
• Customizable markers with names and colors
• A special "North" marker that always points north and can be used to calibrate the app for better accuracy
• Works on iOS and Android devices with modern browsers (Safari, Chrome, etc.)
• Privacy-focused design with encrypted location data and no personally identifiable information stored in the database
• Open source and free to use for anyone with a compatible device and internet connection

FYI: The app is free to use, but hosting is not always free. It relies on Firebase Realtime Database, which has a generous free tier but may incur costs if usage exceeds those limits.

Requirements

• A smartphone with a modern browser that supports geolocation (for example, Safari on iOS or Chrome on Android)
• An internet connection to sync location data in real-time
• Location permissions granted to the browser for the app to access your location
• Camera to scan QR codes (optional, but helps users join rooms faster)
• For best results, use the app outdoors or in areas with good GPS signal, since indoor locations may have reduced accuracy

How to use it?

1. Open Friend Compass.
2. Share the room QR code or room link with your friends so they can join the same "room".
3. Everyone who joins the room can see each other's relative location as an arrow.
4. Everyone can set a custom name and color for their marker.
5. You can hide or reorder friends.
6. The North participant is a special marker that always points north.
7. If North is not pointing to true north, orient your phone so "up" on the screen faces north, then click "Calibrate North". This sets the current orientation as north.
8. A misaligned north is only a visual issue and does not affect actual location sharing.

How does it work?

The app uses Firebase Realtime Database to store and sync location data of all friends in real-time. When a user joins a room, they are added to the database with location and profile info. The app listens for database changes and updates the map accordingly.

Is it secure?

The app does not require authentication, so anyone with the room information can join and see locations of all their friends.

The room link/QR code contains a unique room id and encryption key. Even if someone gained database access (including myself), they could not read location data without the room link.

Share the room QR code/link only with trusted people to protect your privacy.

If a link is leaked or compromised, create a new room and share the new QR code/link with your friends.

Here is a screenshot of database info currently stored (March 2026) for test rooms. Room and friend ids are random strings, and friend info is encrypted. Without the room link, data in the database cannot be tied to real-world identities or locations.

Links

• Repo: GitLab repository
• App: Friend Compass app

Inspiration

Totem Compass and Crowd Compass provide similar functionality, but they are physical products made for off-the-grid use cases such as hiking or festivals where cellular connectivity may be limited.

This app is designed for phone-first scenarios where people want to share location with friends (or strangers) in real-time and have internet connectivity.

Development

Local development

1. Install dependencies:

   bash npm install

2. Run the dev server:

   bash npm run dev

3. Build production artifacts into ./public:

   bash npm run build

4. Preview the production build locally:

   bash npm run preview

Features Implemented

User-Facing Features

• Wake-Lock (Stay-Awake Mode) - Emoji toggle button (💤/🔆) keeps device screen active during tracking
• Toast Notifications - Contextual feedback for compass events, calibration status, and wake-lock actions
• Compass Calibration Feedback - Toast messages for permission denied, enabled, unavailable, and calibrated states
• User Profile Persistence - Custom name and color saved locally and restored on app reload
• Dark Mode Support - Toggle dark mode with persistent preference storage
• Accessibility Improvements - ARIA labels, semantic HTML, and keyboard navigation support

Technical Improvements

• Strict TypeScript Mode - All ~40 files migrated; zero type errors
• Domain-Driven Folder Structure - Organized into src/core, src/features, and src/platform with domain subfolders
• Barrel Index Files - Simplified imports across feature modules
• Naming Convention Standardization - All filenames use underscores, not dashes

Future Work

Planned Features

• Optional user-facing low-power tracking mode toggle (battery saver style control)
• Friend stale-state UX polish (for example: clearer badges, subtle icons, better wording)
• Export/share diagnostics mode for easier field testing (sensor availability, last sync times, etc.)
• Continue migrating behavior-tuning constants into public settings (for example initial seed position and other non-sensitive runtime defaults)

Mobile Platform Support

• React Native + Expo Migration - Reuse ~80% of TypeScript logic (crypto, utils, Firebase sync) while rebuilding the UI layer for iOS/Android native support with background geolocation
• Background Geolocation - Continuous location tracking even when the app is in the background (requires native implementation)
• Battery Optimization - Configurable tracking intervals and geofencing so users can define regions where they care about updates (or where they do not)

Firebase database rules

This repo includes Realtime Database security rules in config/firebase/database.rules.json.

The rules can be deployed using the Firebase CLI, with

npm run firebase:deploy-rules

Without these rules, your database may allow unsafe writes.

Firebase stale room cleanup

The app does not currently implement any automatic cleanup of stale rooms or participants. This means that if a room is created and then abandoned, its data will remain in the database indefinitely.

To clean up stale rooms, we're using GitLab's scheduled pipelines to run a cleanup script every week.

The script can be called manually in preview mode with

npm run clean-old-firebase:preview-30d

and actually executed with

npm run clean-old-firebase:run-30d

Absolute location

I explicitly chose not to expose direct map deep links in the UI, and this feature will not be added.

The app keeps precise coordinates internally for relative-arrow calculations, but intentionally shows only relative directions.

This is a current design choice. Feel free to bring this up in an issue if you have strong feelings about it.

Testing

• BrowserStack test link: Open BrowserStack session
• Firebase console: North Star Firebase console

Is it open source?

You're looking at it.

License

This project is licensed under the MIT License.

Why MIT for this project?

Short version: emotional simplicity and momentum.

• This is a weekend project, and I want low-friction freedom to build, share, and potentially monetize my own work without overthinking legal structure
• I considered stricter licenses (for example AGPL) to make clone monetization harder, but that adds policy/process overhead I do not want right now
• MIT is the simplest path to keep shipping and enjoying the project

Tradeoff accepted:

• MIT allows others to clone and monetize too, including with better marketing
• For this project, that risk is acceptable compared to the cost (time + mental load) of managing a more restrictive licensing setup

If priorities change later (for example, stronger anti-closed-clone goals), future versions can be relicensed with a different strategy.