Fall Guardian

Fall Guardian is a multi-platform fall detection and alert system. It separates fall detection, phone-side alert coordination, caregiver notification, and API persistence into focused projects inside one monorepo.

Product Flow

watch detects possible fall
-> assisted mobile app starts a cancellable countdown
-> uncancelled alert is submitted to the backend API
-> backend stores the alert and notifies linked caregiver devices
-> caregiver app shows the active alert and history
-> caregiver can acknowledge the alert

Cancelled alerts are still part of the backend history so caregivers can see that an assisted user stopped the escalation.

Repository Layout

fall_guardian_monorepo/
├── apps/
│   ├── assisted_mobile/     Flutter app for the assisted person
│   ├── caregiver_mobile/    Flutter app for caregivers
│   ├── wear_os/             native Wear OS watch app
│   └── watchos/             native Apple Watch app
├── backend/
│   └── api/                 Symfony/API Platform backend
├── packages/                reserved for shared contracts or generated assets
├── docs/                    workspace-level documentation
└── scripts/                 workspace automation

Each project keeps its own build system, README, and agent instructions. The root Makefile only orchestrates common checks.

Projects

• backend/api: device identity, invite linking, fall-alert persistence, push dispatch, alert history, acknowledgement, cancellation, rate limiting, and API documentation.
• apps/assisted_mobile: phone app used by the assisted person. It receives watch events, runs the countdown, manages contacts, submits alerts, and lets the user cancel an alert before escalation.
• apps/caregiver_mobile: phone app used by caregivers. It links to one or more assisted persons, registers for push notifications, displays active alerts, and shows alert history.
• apps/wear_os: native Android watch app for Wear OS sensor-based fall detection and handoff to the assisted Android phone.
• apps/watchos: native watchOS app for Apple Watch sensor-based fall detection and handoff to the assisted iPhone.

Local Requirements

• Flutter SDK for the two mobile apps.
• Android Studio, Android SDK, and JDK 17 for Android/Wear OS builds.
• Xcode for iOS/watchOS builds.
• Docker Compose or Podman Compose for the backend.
• GitHub CLI if you need to create or inspect pull requests locally.

The backend Makefile chooses podman compose when Podman is installed, using Podman's stable macOS runtime directory (/private/tmp) so its external Compose provider resolves the machine API socket correctly. It falls back to docker compose otherwise.

Common Commands

Show available root commands:

make help

Run all deterministic checks:

make quality

Run checks for one project:

make quality-api
make quality-assisted
make quality-caregiver
make quality-wear-os
make quality-watchos

Check repository state:

make status

Development Workflow

1. Start from main and pull the latest changes.
2. Create a short-lived branch for the change.
3. Keep changes in the project that owns the behavior.
4. For cross-project contract changes, update the backend and affected apps in the same branch so the feature remains testable end to end.
5. Run the project-level quality command before pushing.
6. Open a PR and wait for CI to pass before merging.

Quality And Security Rules

• Keep automated line coverage at or above 90% when practical.
• Prefer useful tests that verify behavior, contracts, edge cases, and regressions over tests that only execute lines.
• Do not commit secrets, tokens, certificates, signing files, generated native Firebase files, or local machine configuration.
• Use deterministic tools first: formatters, linters, static analysis, tests, builds, dependency scanners, security scanners, and compiler checks.
• Use agent hooks for fast local safety checks.
• Use written guidance and skills for judgment-heavy architecture and review.

API And Device Integration

Default local backend documentation is available at:

http://localhost:8002/docs

Default local API base path:

http://localhost:8002/api/v1

When testing on a wired Android device, the mobile Makefiles can reverse localhost:8002 through ADB with their run-android-wired targets.

More Documentation

Read the project README closest to the code you are changing:

• backend/api/README.md
• apps/assisted_mobile/README.md
• apps/caregiver_mobile/README.md
• apps/wear_os/README.md
• apps/watchos/README.md