fuzzyworld

north-star / files / readme.md

readme.md

Blame: the commit that last changed each line · file · history

e790982a 2026-03-16 Pavel Safronov1# Friend Compass
fb3b6f32 2026-03-14 Pavel Safronov2
e70d53bd 2026-03-15 Pavel Safronov3## What is it?
4
a3080daf 2026-03-17 Pavel Safronov5Friend Compass is a web application that lets users share location in
6real-time with others. It provides a simple interface to see where everyone
7is relative to themselves, and does not require any accounts or
8authentication. Just share the room link or QR code, and everyone can join
9and see each other's location on a map.
10
11## Features
12
13- Real-time location sharing with multiple friends
14- No authentication required, just share the room link or QR code to join
15- No app to install, works on mobile browsers with geolocation support
16- Relative location markers on a map showing direction and distance to each
17 friend
18- Customizable markers with names and colors
19- A special "North" marker that always points north and can be used to
20 calibrate the app for better accuracy
21- Works on iOS and Android devices with modern browsers (Safari, Chrome,
22 etc.)
23- Privacy-focused design with encrypted location data and no personally
24 identifiable information stored in the database
25- Open source and free to use for anyone with a compatible device and
26 internet connection
27
28> FYI: The app is free to use, but hosting is not always free. It relies on
29> Firebase Realtime Database, which has a generous free tier but may incur
30> costs if usage exceeds those limits.
31
32## Requirements
33
34- A smartphone with a modern browser that supports geolocation (for example,
35 Safari on iOS or Chrome on Android)
36- An internet connection to sync location data in real-time
37- Location permissions granted to the browser for the app to access your
38 location
39- Camera to scan QR codes (optional, but helps users join rooms faster)
40- For best results, use the app outdoors or in areas with good GPS signal,
41 since indoor locations may have reduced accuracy
e70d53bd 2026-03-15 Pavel Safronov42
43## How to use it?
44
a3080daf 2026-03-17 Pavel Safronov451. Open [Friend Compass][app-link].
462. Share the room QR code or room link with your friends so they can join the
47 same "room".
483. Everyone who joins the room can see each other's relative location as an arrow.
fb27ecb3 2026-03-15 Pavel Safronov494. Everyone can set a custom name and color for their marker.
a3080daf 2026-03-17 Pavel Safronov505. You can hide or reorder friends.
516. The North participant is a special marker that always points north.
527. If North is not pointing to true north, orient your phone so "up" on the
53 screen faces north, then click "Calibrate North". This sets the current
54 orientation as north.
558. A misaligned north is only a visual issue and does not affect actual
56 location sharing.
e70d53bd 2026-03-15 Pavel Safronov57
58## How does it work?
59
a3080daf 2026-03-17 Pavel Safronov60The app uses Firebase Realtime Database to store and sync location data of all
61friends in real-time. When a user joins a room, they are added to the database
62with location and profile info. The app listens for database changes and
63updates the map accordingly.
e70d53bd 2026-03-15 Pavel Safronov64
ec059e03 2026-03-15 Pavel Safronov65## Is it secure?
66
a3080daf 2026-03-17 Pavel Safronov67The app does not require authentication, so anyone with the room information
68can join and see locations of all their friends.
ec059e03 2026-03-15 Pavel Safronov69
a3080daf 2026-03-17 Pavel Safronov70The room link/QR code contains a unique room id and encryption key. Even if
71someone gained database access (including myself), they could not read
72location data without the room link.
ec059e03 2026-03-15 Pavel Safronov73
a3080daf 2026-03-17 Pavel Safronov74Share the room QR code/link only with trusted people to protect your privacy.
ec059e03 2026-03-15 Pavel Safronov75
a3080daf 2026-03-17 Pavel Safronov76If a link is leaked or compromised, create a new room and share the new QR
77code/link with your friends.
ec059e03 2026-03-15 Pavel Safronov78
a3080daf 2026-03-17 Pavel Safronov79Here is a screenshot of database info currently stored (March 2026) for test
80rooms. Room and friend ids are random strings, and friend info is encrypted.
81Without the room link, data in the database cannot be tied to real-world
82identities or locations.
1e2e4bc1 2026-03-15 Pavel Safronov83
a3080daf 2026-03-17 Pavel Safronov84![Firebase Realtime Database view (March 2026) with encrypted participant
85information][firebase-db-screenshot]
1e2e4bc1 2026-03-15 Pavel Safronov86
ec059e03 2026-03-15 Pavel Safronov87## Links
88
a3080daf 2026-03-17 Pavel Safronov89- Repo: [GitLab repository][repo-link]
90- App: [Friend Compass app][app-link]
ec059e03 2026-03-15 Pavel Safronov91
a3080daf 2026-03-17 Pavel Safronov92## Inspiration
ec059e03 2026-03-15 Pavel Safronov93
a3080daf 2026-03-17 Pavel Safronov94[Totem Compass](https://totemlabs.com/) and
95[Crowd Compass](https://www.crowdcompass.io/) provide similar functionality,
96but they are physical products made for off-the-grid use cases such as hiking
97or festivals where cellular connectivity may be limited.
a402f607 2026-03-15 Pavel Safronov98
a3080daf 2026-03-17 Pavel Safronov99This app is designed for phone-first scenarios where people want to share
100location with friends (or strangers) in real-time and have internet
101connectivity.
a402f607 2026-03-15 Pavel Safronov102
a3080daf 2026-03-17 Pavel Safronov103## Development
ec059e03 2026-03-15 Pavel Safronov104
4e701dc7 2026-03-16 Pavel Safronov105### Local development
106
1071. Install dependencies:
108
a3080daf 2026-03-17 Pavel Safronov109 ```bash
110 npm install
111 ```
4e701dc7 2026-03-16 Pavel Safronov112
1132. Run the dev server:
114
a3080daf 2026-03-17 Pavel Safronov115 ```bash
116 npm run dev
117 ```
4e701dc7 2026-03-16 Pavel Safronov118
1193. Build production artifacts into `./public`:
120
a3080daf 2026-03-17 Pavel Safronov121 ```bash
122 npm run build
123 ```
4e701dc7 2026-03-16 Pavel Safronov124
1254. Preview the production build locally:
126
a3080daf 2026-03-17 Pavel Safronov127 ```bash
128 npm run preview
129 ```
4e701dc7 2026-03-16 Pavel Safronov130
32796e53 2026-03-16 Pavel Safronov131### Features Implemented
0a0cb749 2026-03-15 Pavel Safronov132
32796e53 2026-03-16 Pavel Safronov133#### User-Facing Features
134
a3080daf 2026-03-17 Pavel Safronov135- **Wake-Lock (Stay-Awake Mode)** - Emoji toggle button (💤/🔆) keeps device
136 screen active during tracking
137- **Toast Notifications** - Contextual feedback for compass events,
138 calibration status, and wake-lock actions
139- **Compass Calibration Feedback** - Toast messages for permission denied,
140 enabled, unavailable, and calibrated states
141- **User Profile Persistence** - Custom name and color saved locally and
142 restored on app reload
143- **Dark Mode Support** - Toggle dark mode with persistent preference storage
144- **Accessibility Improvements** - ARIA labels, semantic HTML, and keyboard
145 navigation support
32796e53 2026-03-16 Pavel Safronov146
147#### Technical Improvements
148
a3080daf 2026-03-17 Pavel Safronov149- **Strict TypeScript Mode** - All ~40 files migrated; zero type errors
150- **Domain-Driven Folder Structure** - Organized into `src/core`,
151 `src/features`, and `src/platform` with domain subfolders
152- **Barrel Index Files** - Simplified imports across feature modules
153- **Naming Convention Standardization** - All filenames use underscores, not
154 dashes
32796e53 2026-03-16 Pavel Safronov155
156### Future Work
157
158#### Planned Features
0a0cb749 2026-03-15 Pavel Safronov159
a3080daf 2026-03-17 Pavel Safronov160- Optional user-facing low-power tracking mode toggle (battery saver style
161 control)
162- Friend stale-state UX polish (for example: clearer badges, subtle icons,
163 better wording)
164- Export/share diagnostics mode for easier field testing (sensor
165 availability, last sync times, etc.)
166- Continue migrating behavior-tuning constants into public settings (for
167 example initial seed position and other non-sensitive runtime defaults)
0a0cb749 2026-03-15 Pavel Safronov168
32796e53 2026-03-16 Pavel Safronov169#### Mobile Platform Support
170
a3080daf 2026-03-17 Pavel Safronov171- **React Native + Expo Migration** - Reuse ~80% of TypeScript logic (crypto,
172 utils, Firebase sync) while rebuilding the UI layer for iOS/Android native
173 support with background geolocation
174- **Background Geolocation** - Continuous location tracking even when the app
175 is in the background (requires native implementation)
176- **Battery Optimization** - Configurable tracking intervals and geofencing so
177 users can define regions where they care about updates (or where they do
178 not)
32796e53 2026-03-16 Pavel Safronov179
ec059e03 2026-03-15 Pavel Safronov180### Firebase database rules
2ba7a9cc 2026-03-15 Pavel Safronov181
a3080daf 2026-03-17 Pavel Safronov182This repo includes Realtime Database security rules in
183[config/firebase/database.rules.json](config/firebase/database.rules.json).
2ba7a9cc 2026-03-15 Pavel Safronov184
a3080daf 2026-03-17 Pavel Safronov185The rules can be deployed using the Firebase CLI, with
2ba7a9cc 2026-03-15 Pavel Safronov186
a3080daf 2026-03-17 Pavel Safronov187```bash
188npm run firebase:deploy-rules
189```
2ba7a9cc 2026-03-15 Pavel Safronov190
191Without these rules, your database may allow unsafe writes.
192
a3080daf 2026-03-17 Pavel Safronov193### Firebase stale room cleanup
194
195The app does not currently implement any automatic cleanup of stale rooms or
196participants. This means that if a room is created and then abandoned, its
197data will remain in the database indefinitely.
198
199To clean up stale rooms, we're using GitLab's scheduled pipelines to run a
200cleanup script every week.
201
202The script can be called manually in preview mode with
203
204```bash
205npm run clean-old-firebase:preview-30d
206```
207
208and actually executed with
209
210```bash
211npm run clean-old-firebase:run-30d
212```
213
32796e53 2026-03-16 Pavel Safronov214### Absolute location
215
a3080daf 2026-03-17 Pavel Safronov216I explicitly chose not to expose direct map deep links in the UI, and this
217feature will **not** be added.
218
219The app keeps precise coordinates internally for relative-arrow calculations,
220but intentionally shows only relative directions.
32796e53 2026-03-16 Pavel Safronov221
a3080daf 2026-03-17 Pavel Safronov222This is a current design choice. Feel free to bring this up in an issue if
223you have strong feelings about it.
32796e53 2026-03-16 Pavel Safronov224
a3080daf 2026-03-17 Pavel Safronov225### Testing
226
227- BrowserStack test link: [Open BrowserStack session][browserstack-link]
228- Firebase console: [North Star Firebase console][firebase-console-link]
32796e53 2026-03-16 Pavel Safronov229
ec059e03 2026-03-15 Pavel Safronov230### Is it open source?
e70d53bd 2026-03-15 Pavel Safronov231
232You're looking at it.
233
234### License
235
236This project is licensed under the MIT License.
1a128926 2026-03-15 Pavel Safronov237
238#### Why MIT for this project?
239
240Short version: emotional simplicity and momentum.
241
a3080daf 2026-03-17 Pavel Safronov242- This is a weekend project, and I want low-friction freedom to build, share,
243 and potentially monetize my own work without overthinking legal structure
244- I considered stricter licenses (for example AGPL) to make clone
245 monetization harder, but that adds policy/process overhead I do not want
246 right now
247- MIT is the simplest path to keep shipping and enjoying the project
1a128926 2026-03-15 Pavel Safronov248
249Tradeoff accepted:
250
a3080daf 2026-03-17 Pavel Safronov251- MIT allows others to clone and monetize too, including with better
252 marketing
253- For this project, that risk is acceptable compared to the cost (time +
254 mental load) of managing a more restrictive licensing setup
255
256If priorities change later (for example, stronger anti-closed-clone goals),
257future versions can be relicensed with a different strategy.
1a128926 2026-03-15 Pavel Safronov258
b10cf38c 2026-10-27 Pavel Safronov259[repo-link]: https://code.fuzzyworld.net/north-star/
260[app-link]: https://apps.fuzzyworld.net/north-star/
a3080daf 2026-03-17 Pavel Safronov261[firebase-db-screenshot]: ./firebase-realtime-database-view.png
262[browserstack-link]: https://live.browserstack.com/dashboard#os=iOS&os_version=26.0&device_browser=safari&zoom_to_fit=true&full_screen=true&url=https%3A%2F%2Fpavelsafronov.gitlab.io%2Fnorth-star&speed=1
263[firebase-console-link]: https://console.firebase.google.com/project/north-star-e5dee/overview