# Usalama Parent-Child MVP Technical Specification

**Revision date:** June 13, 2026  
**Status:** Build brief for the first closed-pilot implementation  
**Safety boundary:** Usalama helps children alert trusted adults faster during high-stress situations. It does not guarantee delivery, response, rescue, or safety, and it does not replace `911`, emergency services, law enforcement, direct adult supervision, or professional monitoring.

## Product Boundary

Usalama is a simple child danger alert system. An enrolled child device can trigger **Hold for Help**, notify a verified parent and approved Safety Circle, attach best-available emergency context, and support a clear acknowledgement and response workflow.

The MVP does not include continuous tracking, route history, geofencing, open chat, social features, AI threat detection, school tools, or police integration.

The pilot should not try to prove every possible safety feature. It should prove that parents trust the Safety Circle model and that trusted responders acknowledge and act when an alert occurs.

### Public Positioning

Use:

> Usalama helps children alert trusted adults faster during high-stress situations.

Do not use claims such as “this will save your child,” “guaranteed rescue,” “prevents kidnapping,” “prevents harm,” or “replaces 911.”

## 1. Technical Architecture

```mermaid
flowchart LR
  A["Child app or installed PWA"] -->|"Authenticated Hold for Help"| B["API gateway"]
  B --> C["Incident service"]
  C --> D[("Encrypted PostgreSQL")]
  C --> E["Notification worker"]
  E --> F["Push provider"]
  E --> G["SMS fallback provider"]
  F --> H["Verified parent and Safety Circle"]
  G --> H
  H -->|"Authenticated incident view"| B
  C --> I["Audit service"]
  G -->|"Signed delivery callback"| J["Webhook handler"]
  J --> D
```

### Core services

| Service | Responsibility |
| --- | --- |
| Parent web or mobile client | Parent onboarding, child enrollment, Safety Circle, incident response, logs, deletion controls |
| Child app or installed PWA | Enrolled-device SOS, visible emergency-sharing state, best-available pin, call handoff, and optional pilot audio context |
| API gateway | Authentication, request validation, rate limits, request IDs |
| Incident service | Idempotent incident lifecycle, context attachment, role checks, resolution |
| Notification worker | Parent and Safety Circle push notification, SMS fallback, retries, delivery tracking |
| Audit service | Consent, guardian changes, device changes, location access, incident access, admin actions |
| PostgreSQL | Encrypted persistent records with retention and deletion policies |

### Incident lifecycle

`arming -> canceled | dispatching -> active -> resolved`

Rules:

- SOS creation happens before location or optional audio capture.
- Context capture is best-effort and cannot block dispatch.
- Location is incident-scoped, not a background stream.
- Resolution ends guardian access to emergency location and begins the retention countdown.
- Test incidents are visibly classified and must never resemble a live alert.
- Safety-critical modals should not be dismissible by backdrop click or Escape without a visible action such as cancel, send, close error, or resolve.

## 2. Database Schema

The first schema is scaffolded in [`mvp-scaffold/db/schema.sql`](./mvp-scaffold/db/schema.sql).

| Table | Purpose |
| --- | --- |
| `accounts` | Verified parent account and consent holder |
| `children` | Child safety profile linked to a parent |
| `devices` | Registered parent and child devices with revoke state |
| `guardian_invites` | Verified Safety Circle invitation and acceptance lifecycle |
| `safety_circle_members` | Approved guardian role and time-limited access settings |
| `incidents` | Child SOS lifecycle, classification, timestamps, retention |
| `incident_context` | Best-available pin and optional pilot audio reference for one incident |
| `incident_participants` | Which parent or guardian can access one active incident |
| `deliveries` | Push and SMS attempts per recipient |
| `acknowledgements` | Which trusted responders acknowledged an alert and when |
| `location_access_logs` | Who accessed a child's emergency pin and when |
| `audit_events` | Consent, device, guardian, incident, deletion, and admin actions |
| `deletion_requests` | Parent-facing deletion workflow |
| `pilot_consents` | Parent waiver, emergency disclaimer, data handling summary, abuse-prevention acknowledgement, and policy versions |

## 3. API Routes

The route inventory is scaffolded in [`mvp-scaffold/api/routes.md`](./mvp-scaffold/api/routes.md).

### Parent and child setup

| Method | Route | Purpose |
| --- | --- | --- |
| `POST` | `/v1/parents/register` | Create verified parent account |
| `POST` | `/v1/parents/sessions` | Create parent session with strong auth |
| `POST` | `/v1/parents/consents` | Record parent consent, beta waiver, emergency disclaimer, data handling summary, and abuse-prevention acknowledgement |
| `POST` | `/v1/children` | Add child profile |
| `POST` | `/v1/children/:childId/devices/enroll` | Enroll child device |
| `POST` | `/v1/devices/:deviceId/revoke` | Parent revokes a lost child device |
| `POST` | `/v1/children/:childId/guardians/invites` | Invite a Safety Circle guardian |
| `POST` | `/v1/guardian-invites/:token/accept` | Guardian accepts verified invite |
| `DELETE` | `/v1/children/:childId/guardians/:guardianId` | Parent revokes guardian access |

### Emergency workflow

| Method | Route | Purpose |
| --- | --- | --- |
| `POST` | `/v1/incidents` | Child device creates idempotent live or test incident |
| `POST` | `/v1/incidents/:incidentId/context/location` | Attach one best-available emergency pin |
| `POST` | `/v1/incidents/:incidentId/context/audio` | Attach optional 5-second audio-context reference after dispatch begins |
| `GET` | `/v1/incidents/:incidentId` | Authorized participant opens incident screen |
| `POST` | `/v1/incidents/:incidentId/actions/call-child` | Record call-child handoff action |
| `POST` | `/v1/incidents/:incidentId/actions/call-emergency-services` | Record emergency-services handoff action |
| `POST` | `/v1/incidents/:incidentId/actions/acknowledge` | Record trusted-responder acknowledgement |
| `POST` | `/v1/incidents/:incidentId/resolve` | Authorized parent resolves incident |
| `POST` | `/v1/webhooks/messaging/:provider` | Verify provider callbacks and update deliveries |

### Trust controls

| Method | Route | Purpose |
| --- | --- | --- |
| `GET` | `/v1/children/:childId/incidents` | Minimal retained incident log |
| `GET` | `/v1/children/:childId/location-access-logs` | Parent reviews emergency-pin access |
| `POST` | `/v1/deletion-requests` | Parent requests child, incident, or account deletion |
| `GET` | `/v1/deletion-requests/:requestId` | Parent checks deletion status |

## 4. User Flows

### Parent setup

1. Parent registers and completes strong authentication.
2. Parent accepts consent, beta waiver, emergency disclaimer, data handling summary, and abuse-prevention limitations.
3. Parent creates a child profile.
4. Parent enrolls the child's device.
5. Parent invites Safety Circle guardians.
6. Each guardian verifies and accepts the invite.
7. Parent can review or revoke guardians and devices.

### Child Hold for Help

1. Child presses and holds SOS for three seconds.
2. A short cancellation window protects against accidental presses.
3. The enrolled device creates an idempotent incident.
4. The backend begins parent and Safety Circle notification immediately.
5. The child device requests one current position and submits it if available.
6. Escalation starts with the parent, then backup contacts, then the full Safety Circle if acknowledgement is delayed.
7. In the pilot add-on, the device may submit an optional, explicit 5-second audio context clip after dispatch begins.
8. The child sees that emergency sharing is active and who receives the alert.

### Parent response

1. Parent opens the authenticated incident notification.
2. Parent sees child identity, timestamp, alert status, best-available pin, and Safety Circle delivery and acknowledgement state.
3. Parent or approved responder can acknowledge the alert.
4. Parent can call the child.
5. Parent can call emergency services with clear language that Usalama is not a replacement.
6. Parent resolves the incident when appropriate.
7. Resolution expires location access and records the resolver.

### Safe check-in

1. Child presses **I'm Safe**.
2. Parent receives a simple non-emergency update with child name and timestamp.
3. No location is requested unless the parent-child pilot rules explicitly approve it.

### Trust review

1. Parent reviews minimal incident history.
2. Parent reviews who accessed the child's emergency pin.
3. Parent removes guardians or revokes lost devices.
4. Parent requests deletion of child, incident, or account data.

## 5. Component And Screen List

### Parent surfaces

| Screen | Core components |
| --- | --- |
| Parent registration | Strong-auth handoff, consent summary, emergency disclaimer |
| Parent home | Child cards, enrollment state, current incident banner |
| Child profile | Child identity, enrolled devices, revoke action |
| Safety Circle | Verified guardian list, invite, acceptance state, revoke |
| Parent incident screen | Child identity, timestamp, emergency pin, delivery state, acknowledgements, escalation state, **Call child**, **Call emergency services**, **Resolve incident** |
| Incident log | Minimal retained records and classifications |
| Location access log | Actor, role, incident, timestamp, reason |
| Privacy and deletion | Data summary, deletion request, request status |

### Child surfaces

| Screen | Core components |
| --- | --- |
| Child home | **Hold for Help**, **I'm Safe**, visible enrolled state, test mode |
| SOS arming | Three-second progress ring and visible state label |
| Cancel window | Countdown, cancel, send immediately, locked modal until explicit action |
| Emergency active | Sharing status, notified-circle summary, best-available context state, response-action handoff |
| Test complete | Clear test classification and no live-delivery language |

### Safety Circle surface

| Screen | Core components |
| --- | --- |
| Guardian incident view | Child identity, active emergency pin, timestamp, **Acknowledge alert**, **Call child**, **Call emergency services**, expiry notice |

## 6. Security Assumptions

- Parent accounts use a mature authentication provider with passkeys or MFA.
- Every Safety Circle guardian verifies and accepts an invitation.
- Parent, child device, and guardian sessions are bound to registered devices where supported.
- Authorization is server-side and role-based. Client UI is never the security boundary.
- Emergency context is incident-scoped, encrypted at rest and in transit, and retained briefly.
- There are no public child profiles, search-by-child routes, or public location links.
- Every emergency-pin access is logged.
- Every admin action involving sensitive records is logged with a reason code.
- API endpoints are rate-limited by account, device, and IP; incident creation is idempotent.
- Messaging provider callbacks are signature-verified.
- Vendor DPAs and cross-border review are required before real delivery.
- The detailed release gates live in [`MISUSE_PREVENTION_PLAN.md`](./MISUSE_PREVENTION_PLAN.md).

## 7. MVP Implementation Plan

### Workstream A: Identity and enrollment

- Parent authentication, consent, emergency disclaimer, beta waiver, data handling summary, abuse-prevention acknowledgement, and recovery.
- Child profiles.
- Child-device enrollment and parent revoke.
- Verified Safety Circle invitations and roles.

### Workstream B: Incident lifecycle

- Idempotent incident creation.
- One-time pin attachment.
- Alert acknowledgement.
- Escalation workflow.
- Optional pilot audio-reference attachment after dispatch.
- Authenticated incident views.
- Visible incident state progression and response-action UI.
- Resolution and expiry.

### Workstream C: Notifications and response

- Push notification or primary alert channel.
- SMS fallback.
- Signed provider callbacks, retry policy, and degraded states.
- Parent and guardian call-handoff actions.
- Safe check-in message.

### Workstream D: Trust controls

- Minimal incident log.
- Emergency-pin access log.
- Parent deletion requests.
- Admin audit trail, rate limits, anomaly alerts, and support runbook.

## 8. Known Platform Limitations

| Limitation | Impact | MVP handling |
| --- | --- | --- |
| PWA push behavior differs across iOS and Android | Delivery cannot be assumed | Use measured delivery plus SMS fallback; plan native clients for supervised beta |
| Browser geolocation can be denied, delayed, or inaccurate | Pin may be unavailable | Dispatch first, request one pin in parallel, display truthful status |
| Microphone permission can be denied | Audio context may be unavailable | Keep audio optional, explicit, short, and non-blocking |
| Background execution is constrained | PWA cannot behave like emergency infrastructure | Keep the MVP honest; validate native apps for deeper reliability |
| SMS delivery varies by provider and country | Message arrival is not guaranteed | Track callbacks, retries, throughput, and supported-country limits |
| Device biometrics are mediated by the operating system | App cannot read or store fingerprints or face templates | Use platform verification only for account protection |
| `tel:` call handoff depends on device support | Call action may not complete | Show the phone action clearly and record only the handoff request |
| Offline devices cannot reach the backend | SOS cannot be dispatched | Show an unmistakable offline failure state and retry when connectivity returns |

## 9. Development Milestones

| Milestone | Deliverable | Exit criteria |
| --- | --- | --- |
| M0: Approved scope | Technical spec, misuse plan, non-goals | Product, legal, safety, and engineering owners agree |
| M1: Parent-child foundation | Auth, consent, child profile, device enrollment, guardian invites | Parent can enroll and revoke a child device; guardian access requires verified acceptance |
| M2: Incident core | SOS create, pin attachment, incident screen, acknowledgement, escalation, safe check-in, resolution | Enrolled child creates one incident; authorized parent sees pin when available, acknowledgement state is visible, escalation is recorded, and parent resolves |
| M3: Delivery | Primary notification, SMS fallback, callbacks, retries, response-action recording | Verified recipients receive measured alerts with truthful status; acknowledgement, call-child, and emergency-service handoffs are recorded |
| M4: Trust controls | Access logs, deletion requests, admin audits, limits | Parent can review location access and request deletion; misuse gates pass |
| M5: Closed pilot readiness | QA, support runbook, threat model, vendor review | Cross-functional go or no-go review approves a supervised cohort |

## Scaffold

The first production-track scaffold lives in [`mvp-scaffold`](./mvp-scaffold). It is intentionally separate from the live investor demo so the demo remains stable while the parent-child MVP is built.