곁애 (Gyeoae)

English · 한국어

Your phone can quietly help a lost elder find the way home.

당신의 폰이 누군가의 귀갓길을 조용히 도울 수 있어요.

곁애 ("by your side") is a free, open-source, public-good service that helps find people with dementia who wander and get lost — especially where there is no mobile network. The person carries a tiny Bluetooth (BLE) tag that broadcasts only an anonymous, rotating ID. Any nearby phone with the app detects it offline, remembers the sighting, and uploads it automatically once it's back in signal. Neighbours passing by are what makes it work.

It is the automatic layer on top of Korea's existing missing-person alert: when an alert is on, nearby phones search for the tag by themselves — phones matching an ID, instead of people trying to match a description on the street. And through all of it, a bystander never learns who the person is — only that "someone may need help."

Project lead: CLSOFTLAB (씨엘소프트랩), Dr. Lee Il-guk (이일국 박사). No money, no ads, no data sale, no keys required.

[!NOTE] Status: v0.1 reference design + working app/backend. 곁애 is an assistive, community aid. It is not a medical device and not an emergency service. If someone is in danger now, call 112 (police) or 119 (fire/medical) in Korea first.

---

How it works

Detect offline → store on the phone → auto-upload when back online. The finder does nothing extra; nothing is lost even if they never open the app again.

  NO-NETWORK AREA (trail, field)                     BACK IN SIGNAL
  ──────────────────────────────                     ──────────────
  person with dementia carries a BLE tag             finder's phone auto-uploads the
  → broadcasts a rotating ANONYMOUS id               saved sighting to the guardian network
        │  (offline, no internet)                            │
        ▼                                                     ▼
  a passer-by's phone hears it                        guardian is notified: "seen near X at 14:20"
  → saves { tag id (hashed), coarse GPS, time }       citizen only ever saw
     ON THE PHONE — no network needed                 "someone may need help + report"
  → shows a gentle "help & report" card               guardian / verified police act
        │                                             (identity + exact place: them only,
        └── guardian nearby? offline voice homing:     audit-logged)
            "getting closer… about 20 m, this way"

The missing-person-alert connection: Korea already sends wandering-alert text messages to people nearby, then asks a human to match a written description on the street — the weak link. 곁애 replaces that step: when an alert is on, nearby phones automatically look for the tag. The SMS reaches people; 곁애 makes their phones search. See docs/en/07-missing-person-alert-link.md.

Try it now — in your browser, no hardware, no keys

The built-in demo / simulator plays the whole story on one screen: a tag moving through a no-signal zone, several phones detecting it offline and uploading when back online, and a guardian homing in — with no hardware and no keys.

• Hosted demo (once GitHub Pages is published): https://clsoftlab-lang.github.io/gyeoae/app/
• Run it locally now:

  cd app && python -m http.server 8080      # open http://localhost:8080 → 시민 → demo
  

Watch what the citizen sees: only "someone may need help" — never a name, photo, or the word "dementia". See docs/en/01-quickstart.md.

What's built vs. what an operator adds

곁애 gives you the working software and the design. Turning it into an at-scale public service needs a few things that only an operator, or an authority, can put in place.

✅ Built in this repository	⚠️ An operator / authority adds later
Citizen, guardian and police/keeper PWA apps	Native app for reliable background scanning (esp. iOS)
Small FastAPI + SQLite API, runs with no keys	Real hosting, accounts, and scaled database
Offline store-and-forward (detect offline, queue, auto-upload)	Official missing-person-alert integration (auto-search on alert)
Rotating-ID privacy so no one can track the person over time	Police / safety-keeper verification authority
Coarsening of shared locations; audit-logged identity access	Satellite / LoRa bridge for true wilderness with no passer-by
Guardian offline voice homing (getting warmer/colder)	Community rollout with carer organisations
Citizen "no-identity" help card (bystanders see no identity)	Legal, safety and data-protection review for a live deployment
In-browser demo / simulator, no hardware needed

Privacy & dignity

[!IMPORTANT] Bystanders never see identity. A passer-by only ever sees "someone may need help" — never a name, photo, or the word "dementia". Identity and exact location are for the registered guardian and verified police only, and every such access is audit-logged.

Why: telling a stranger that a specific, findable person is confused and alone is exactly what a kidnapper or scammer would want, and publicly labelling someone with a condition harms their dignity for good. A citizen can help perfectly well without knowing who the person is — knowing would add nothing but risk. The tag broadcasts a rotating anonymous ID so no one can follow the person over time, shared locations are coarsened, enrolment needs consent, and data can be exported or deleted. No ads, no data sale, finders are not tracked. → docs/en/05-privacy-safety-dignity.md

Safety

[!WARNING] 곁애 is not a medical device and not an emergency service. It does not monitor health and is not guaranteed real-time. In an emergency, call 112 (police) or 119 (fire/medical) in Korea first; for a missing person, contact the police (안전Dream / 실종경보). The citizen app coaches a gentle, dignified response: don't startle the person, stay with them if it is safe, and help them feel safe while a guardian or the police are reached. 곁애 complements — it does not replace — GPS wander-detectors (배회감지기), police fingerprint pre-registration (지문 사전등록), and the official alert system.

Honest limits

[!NOTE]

• Reliable background scanning needs a native app. Web apps can scan only in the foreground (and iOS is especially restrictive). Foreground scanning and guardian homing work today; all-day background detection is on the roadmap as a native app.
• If no phone ever passes by (true wilderness), no crowd-powered app can help — that needs satellite / long-range radio (LoRa), a future track.
• 곁애 is a finding layer, not a tracker. Sightings are occasional, best-effort, and expire. → docs/en/06-deploy-and-limits.md

Repository

Folder / file	What	Licence
app/	Citizen / guardian / keeper PWA — offline BLE scan, store-and-forward queue, homing, in-browser demo/simulator	Apache-2.0
backend/	Small FastAPI + SQLite API — enrol tags, receive & coarsen sightings, match rotating IDs, access-controlled identity, audit log. Runs with no keys	Apache-2.0
docs/	Design spec and guides (English + 한국어)	CC BY 4.0
.github/	Issue templates, PR template, CI	Apache-2.0

Dev quick start

Everything runs locally with no keys and no secrets. Authoritative commands live in backend/README.md and app/README.md (as populated); the essentials:

# 1) Backend API (FastAPI + SQLite)
cd backend
python -m venv .venv && . .venv/bin/activate       # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
uvicorn gyeoae.app:app --reload                     # http://127.0.0.1:8000

# 2) Frontend PWA + demo (no build step)
cd app
python -m http.server 8080                          # http://localhost:8080

# 3) Tests
cd backend && pytest
cd app && node --test tests/*.test.js

Copy backend/.env.example to backend/.env only to change a default — never put real secrets there. See docs/en/01-quickstart.md.

How the tag and the offline network work, simply

Rotating anonymous IDs. Each tag has a secret known only to the guardian's app and the server; it is never broadcast. The tag emits a keyed hash of the current 15-minute time window, so the broadcast ID changes constantly and looks like unrelated random tokens to everyone else. Only a holder of the secret (the guardian app + the server) can recognise it, by recomputing the IDs for the time a sighting was seen. So the guardian and the network can match the tag, while a bystander can neither identify nor track the person. → docs/en/03-ble-and-privacy.md

Store-and-forward. In a no-signal area, a passer-by's phone detects the tag with no internet, records { tag id (hashed), coarse GPS, time } in a local queue that survives reboots, and uploads on its own the moment it regains signal. The sighting carries both when it was seen and when it was uploaded; matching keys off when it was seen, so a delayed upload still finds the right tag. Neighbours are the network — no infrastructure to install. → docs/en/04-offline-store-and-forward.md

For families & carers / partner organisations

If you care for someone who might wander — or you are a care facility, a dementia support group, a local government, a police or safety-keeper programme, a researcher, or a maker group — we would love to hear from you. 곁애 is free and non-commercial; there is nothing to buy. It becomes a real safety net only when neighbours and local services take part.

• Say hello / propose working together: open a partner inquiry or a Discussion.
• Tell us where the design would help or get in the way — your experience shapes it.
• Please don't post anyone's private data in a public issue; for anything sensitive we'll move to a private channel.

Start here: docs/README.md · CONTRIBUTING.md

Contributors

• CLSOFTLAB (씨엘소프트랩), Dr. Lee Il-guk (이일국 박사) — project lead
• LWJ · LMJ
• Designed and built with Claude (Anthropic's AI)

Licences

• Software: Apache-2.0
• Documentation: CC BY 4.0

Details in NOTICE. © 2026 CLSOFTLAB (씨엘소프트랩), Dr. Lee Il-guk (이일국).

Not an Anthropic product. 곁애 is an independent public-good project by CLSOFTLAB, designed with the help of Claude. It is not made, endorsed by, or affiliated with Anthropic.

Sister projects

More free, open public-good projects from github.com/clsoftlab-lang:

• open-walking-safety-helmet — a helmet that helps blind and low-vision people walk safely
• robosoul-humanoid — an open humanoid robot project
• fireflies — helium LED "jellyfish" night-sky art
• ieodalligi — 이어달리기
• ongigil — 온기길, calm offline voice guidance (reused for guardian homing here)