곁애 (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.
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
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:
