323 lines
22 KiB
Markdown
323 lines
22 KiB
Markdown
# Who Need Help — implementation verification
|
|
|
|
Observed on 2026-07-18 in the local workspace. This report separates observed
|
|
results from product limits and unknown production properties.
|
|
|
|
## Verified MVP capabilities
|
|
|
|
| Requirement | Status | Observed evidence | Limit |
|
|
| --- | --- | --- | --- |
|
|
| Urgent medicine-help flow | Implemented and tested | Request creation, discovery, matching, start, handover, two-party completion, and review rules are covered by the Phoenix test suite and exercised in the local UI. | The product coordinates pickup of an already purchased or reserved legal item; it is not a pharmacy, medical, or emergency service. |
|
|
| Urgent roadside help | Implemented and tested | Fuel, car wheel, bicycle, motorcycle, vehicle-breakdown, and secured-incident categories are seeded as a translated hierarchy. Server and LiveView tests exercise category paths, required fields, allowed values, boolean normalization, unknown-field rejection, and request creation. | Roadside requests require no immediate danger; this is not emergency response or professional recovery. |
|
|
| Extensible categories | Implemented and tested | Categories and validated text/select/boolean fields are stored in PostgreSQL. Proposal, vote, approve, reject, and merge paths have automated tests. | Coffee, cinema, hiking, and other social activities remain separate from urgent-help safety and ranking rules. |
|
|
| Separate Activity mode | Implemented and tested | Coffee, cinema, walk, and hiking categories use a separate activity lifecycle. Domain and two-client LiveView tests cover creation, join request, organizer approval, capacity enforcement, public/pending/chat privacy, exact-location disclosure to approved users, group chat, blocking, completion, and zero impact on helper reputation. Activity and message reports expose only the linked group conversation to an audited moderator; moderators can hide and restore reported activities. | This does not guarantee participant identity or physical safety. |
|
|
| Map and discovery | Implemented and browser-verified | A headed Chrome session rendered the MapLibre request map, marker, controls, attribution, and configured OpenStreetMap raster tiles. Tile requests returned HTTP 200 during the check. | A production operator must configure a tile provider appropriate for its policy and traffic. |
|
|
| Private matched chat | Implemented and cross-client verified | A message sent from the helper browser appeared in the requester's browser without reload. An earlier Android emulator run also sent a message that appeared in the requester browser in real time. | There is no unsolicited general-purpose inbox. |
|
|
| Consent-driven live tracking | Implemented and cross-client verified | On API 37, Android started `TrackingService` as a location foreground service with a persistent Stop notification. After Home minimized the Activity, an emulator coordinate change reached PostGIS. Notification Stop removed the service, notification, active session, and raw position. | Browsers stop with the page. Android has no `ACCESS_BACKGROUND_LOCATION`, unattended start, or route history. |
|
|
| Privacy settings | Implemented and browser-verified | The profile exposed hidden, approximate public, exact for active match, and explicit exact-public options. Blocking and current-position cleanup have automated tests. | Exact public location remains a user opt-in; legal privacy and retention text still requires jurisdiction-specific review before launch. |
|
|
| Reputation and anti-abuse | Implemented at MVP level | Handover codes, two-party completion, double-blind reviews, unique-counterpart ranking, optional movement/proximity evidence, reports, blocks, abuse signals, and moderator audit paths have automated tests. | The system is not bot-proof and does not claim identity verification. No punitive numeric policy is enabled without measured and approved thresholds. |
|
|
| Social profiles | Manual links implemented; GitHub verification implemented and automated-tested | Manual links cannot set verification fields. The optional GitHub flow uses state, PKCE, a user-bound one-time session, unique provider ownership, and an audit record; 149 tests pass, including callback replay/state checks. No access-token field exists and the controller receives only normalized identity attributes. | The staging operator has not supplied GitHub OAuth credentials, so the real external provider redirect/callback remains disabled and has not been browser-verified. Other providers remain manual/unverified. |
|
|
| Voluntary thanks | Implemented as an external optional link | A helper can expose an optional link after completion; the UI states that the platform does not process the payment. | The platform does not provide payments, escrow, refunds, tax reporting, or payment guarantees. |
|
|
| Android client | Local and public-staging clients implemented and emulator-verified | The native packages `org.whoneedhelp.mobile.debug` and `org.whoneedhelp.mobile.staging` launch the same authenticated LiveView app. Public HTTPS login, map, two-way chat, permission prompts, minimized foreground-service location updates, notification Stop, deep-link routing, and server cleanup were exercised on API 37. | Production signing, Play Store publication, verified Android App Links, unattended/background-permission tracking, and iOS are not implemented. |
|
|
| Multiple web/worker instances | Implemented and locally verified | Docker Compose and kind each ran 2 web and 2 worker replicas. The project probes cross-node Phoenix PubSub using different BEAM nodes. Kubernetes web/worker pods were Ready with zero restarts at the final observation. | Local PostGIS is a single instance. Production database HA, backups, and recovery are operator work and are not claimed complete. |
|
|
|
|
## Reproducible checks
|
|
|
|
- `./scripts/test.sh`: 149 tests, 0 failures after the Android public-staging and
|
|
realtime tracking-evidence changes
|
|
on Elixir 1.20.2 and Erlang/OTP 29.0.3.
|
|
- `mix compile --force --warnings-as-errors` and
|
|
`mix format --check-formatted`: passed against the same final source.
|
|
- The generated Activity migration was rolled back by exactly one step and
|
|
migrated forward again against `who_need_help_test`; both directions passed.
|
|
- The Activity-report migration was also rolled back and migrated forward. The
|
|
observed database constraint changed from exactly one of 3 urgent-help
|
|
targets to exactly one of 5 urgent-help/Activity targets.
|
|
- `mix format --check-formatted`: passed in the final run.
|
|
- Android local Docker build target: `testDebugUnitTest`, `lintDebug`,
|
|
`assembleDebug`, and `assembleDebugAndroidTest` passed. The isolated API 37
|
|
runner then passed 5/5 instrumentation tests for denied/granted location
|
|
permission, deep-link lifecycle, foreground location upload, notification
|
|
Stop, and disconnected-Stop retry state. The public-staging target ran the
|
|
unit tests plus `lintStaging` and `assembleStaging`; both previously recorded
|
|
lint reports contain no errors or warnings.
|
|
- Release Android guard: a release build without `WNH_BASE_URL` failed as
|
|
intended; release configuration accepts only an explicit HTTPS origin.
|
|
- Helm lint, template rendering, server-side dry-run, rollout waits, readiness
|
|
checks, and cross-node PubSub verification passed in the local kind cluster.
|
|
- Browser verification used headed Chrome. The authenticated matched-request
|
|
page rendered its chat, MapLibre marker, and live-location controls with no
|
|
console errors or warnings after the foreground-service rollout.
|
|
|
|
Local generated evidence (ignored by Git):
|
|
|
|
- `output/playwright/final-request-map-chat.png`
|
|
- `output/playwright/final-privacy-profile.png`
|
|
- `output/android/final-image-smoke.png`
|
|
- `output/android/foreground-notification.png`
|
|
- `output/android/staging-deep-link-safety.png`
|
|
- `output/android-instrumentation/20260718225400-2694340/results.txt`
|
|
|
|
Android artifact:
|
|
|
|
- `android/dist/who-need-help-debug.apk`
|
|
- SHA-256:
|
|
`4520aa0b50eaf53bb7052e7f4c096a73d456f45781380187586c79d7267c21c5`
|
|
- `android/dist-staging/who-need-help-staging.apk`
|
|
- SHA-256:
|
|
`08d990a9268a382052be5f2d3ba5afba2aa65a9ad5f9ae1ad4bff720f8999a6e`
|
|
- Observed staging manifest values: package
|
|
`org.whoneedhelp.mobile.staging`, version `0.1.0-staging`, minimum SDK 24,
|
|
target and compile SDK 37, cleartext traffic disabled, `singleTop`
|
|
`MainActivity`, and an exact HTTPS host of `whoneedhelp.imalto.site`.
|
|
- `apksigner verify` accepted the staging artifact's v2 generic debug
|
|
signature. That signing identity is only for installable staging verification
|
|
and is not a production release identity.
|
|
|
|
## Configuration finding
|
|
|
|
`WNH_DEBUG_BASE_URL` is a required Android build input, because the trusted
|
|
same-origin value is compiled into the debug APK. Its concrete local value is
|
|
read from the repository's ignored `.env` by `scripts/android-build.sh` and is
|
|
passed to Docker with `--build-arg`. `android/Dockerfile` only declares
|
|
`ARG WNH_DEBUG_BASE_URL`; it contains no URL default.
|
|
|
|
The example `http://10.0.2.2:4010` remains only as unit-test data for origin
|
|
matching. It is not a runtime or build default. The ignored `.env` is also
|
|
excluded from the root Docker build context.
|
|
|
|
## Database observations
|
|
|
|
The post-roadside local Compose observation found 2 users, 1 help request, 7
|
|
messages, and 1 assignment before and after deployment. Category seeding
|
|
changed only the category count from 1 to 9: 7 selectable categories and 2
|
|
inactive grouping nodes. These are local scenario data; the database is not
|
|
assumed empty.
|
|
|
|
The Activity migration then preserved those same user/help/message/assignment
|
|
counts, added empty `activities`, `activity_participants`, and
|
|
`activity_messages` tables, and expanded the category tree to 14 rows: 9 help
|
|
rows and 5 Activity rows. A validated custom-format dump was created immediately
|
|
before that migration at
|
|
`output/backups/compose-before-activity-20260718-203930.dump`; this ignored local
|
|
artifact is not a substitute for the still-required isolated restore drill.
|
|
|
|
The final kind observation found 0 users, 0 help requests, and 0 messages. That
|
|
state was queried before changing the database workload. The migration from the
|
|
old `emptyDir` Deployment created a custom-format dump, validated it with
|
|
`pg_restore --list`, changed PostGIS to a persistent StatefulSet, and restored
|
|
the dump before the Helm upgrade. The final kind database reported PostgreSQL
|
|
18.4 and PostGIS 3.6.4.
|
|
|
|
The local kind Secret contains independently generated values. Only their
|
|
decoded lengths were inspected: the PostgreSQL password is 64 characters and
|
|
each application secret is 128 characters. Secret values were not printed or
|
|
written to tracked files.
|
|
|
|
## Dependency-upgrade observations
|
|
|
|
- The running Compose and kind releases reported Elixir 1.20.2 and Erlang/OTP
|
|
29.
|
|
- Compose reported Traefik 3.7.8 and Mailpit 1.30.4; Compose and kind both
|
|
reported PostgreSQL 18.4 and PostGIS 3.6.4.
|
|
- The production asset build reported Tailwind CSS 4.3.3 and daisyUI 5.6.18;
|
|
esbuild is configured at 0.28.1.
|
|
- The isolated Node build stage reported Node.js 24.18.0, npm 12.0.1,
|
|
`npm outdated --json` returned `{}`, and `npm ci` reported zero known
|
|
vulnerabilities.
|
|
- The Android build used Android Gradle Plugin 9.3.0, Gradle 9.6.1, Command-line
|
|
Tools 22.0, and its embedded Android CLI 1.0.15857036. Unit tests, lint, and
|
|
debug assembly passed; the lint report says “No errors or warnings.” The
|
|
rebuilt emulator image contains the API 37 ps16k AVD and APK, and its emulator
|
|
36.6.11.0 binary returned its version successfully at runtime.
|
|
- The final complete `scripts/kind-up.sh` run was idempotent and finished with
|
|
both 2-replica Deployments Ready and a successful cross-replica PubSub probe.
|
|
|
|
The migration `20260718114233` and reverse block lookup index
|
|
`blocks_blocked_id_blocker_id_index` were present. An actual `EXPLAIN ANALYZE`
|
|
for that reverse lookup selected the index. The table contained no block rows,
|
|
so this confirms query shape, not production performance.
|
|
|
|
Exact production capacity, minimum CPU/RAM, and scaling thresholds are unknown:
|
|
there is no representative load dataset or target-environment measurement. An
|
|
isolated 40 HTTP VU / 40 WebSocket VU local comparison is recorded in
|
|
`docs/performance.md`; it tested a paced public/readiness/heartbeat workload
|
|
with 2 and 3 web replicas but did not find a saturation point. The Helm chart
|
|
therefore does not invent resource limits or an HPA policy.
|
|
|
|
## Public staging observation
|
|
|
|
On 2026-07-18, `whoneedhelp.imalto.site` was published through the existing
|
|
Ubuntu Nginx gateway and its OpenVPN path to the local Compose proxy. HTTP
|
|
redirected to HTTPS; the homepage, fingerprinted assets, and both health
|
|
endpoints returned HTTP 200. A headed Chrome session rendered the public page
|
|
with zero console errors or warnings. A complete WebSocket Upgrade request to
|
|
`/live/websocket` returned `101 Switching Protocols`.
|
|
|
|
The observed Let's Encrypt certificate had the correct
|
|
`DNS:whoneedhelp.imalto.site` SAN and an expiry of 2026-10-16. Nginx and the
|
|
Certbot renewal timer were active. This verifies the current staging path; it
|
|
does not make the workstation or gateway a production availability
|
|
environment.
|
|
|
|
After the Activity rollout, headed Chrome rendered the updated public
|
|
navigation, followed the Activity link to the authenticated route, and received
|
|
the expected login redirect and flash with zero console errors or warnings.
|
|
|
|
After commit `307794c`, staging was rebuilt with the optional GitHub OAuth
|
|
boundary. Both web and both worker replicas started, the cross-node PubSub probe
|
|
passed, public home/readiness returned HTTP 200, and the before/after database
|
|
counts remained `2 users / 1 request / 7 messages / 14 categories / 1
|
|
assignment / 0 activities / 0 reports / 0 social identities`.
|
|
|
|
A headed Chrome E2E run then registered a uniquely named `example.invalid`
|
|
account, consumed its confirmation link from local Mailpit, authenticated,
|
|
opened `/profile`, and observed:
|
|
|
|
- the GitHub network option and the explicit provider-disabled explanation;
|
|
- no Verify button while both OAuth environment variables were absent;
|
|
- a manually added Telegram link labelled `unverified`;
|
|
- removal of that owner-controlled manual link;
|
|
- a direct `/auth/social/github` request returning to the profile with the
|
|
controlled `provider is not configured` flash;
|
|
- zero browser console errors or warnings.
|
|
|
|
The exact E2E user was checked for every foreign-key relationship to `users`.
|
|
It had only its one authentication token and no domain records after the manual
|
|
link was removed. That exact user was then deleted through Ecto, its browser
|
|
session became invalid, the generated Mailpit message was deleted individually,
|
|
and the original database counts were observed again. The browser windows were
|
|
left open.
|
|
|
|
Local ignored browser evidence:
|
|
|
|
- `.playwright-cli/page-2026-07-18T18-09-44-303Z.png`
|
|
|
|
## Public Android and cross-client observation
|
|
|
|
The public-staging APK was built with the explicit ignored `.env`
|
|
`WNH_BASE_URL`, installed on the API 37 emulator, and connected to
|
|
`https://whoneedhelp.imalto.site`. Android package inspection found exactly one
|
|
matching Activity for the configured HTTPS host and no matching Activity for
|
|
`attacker.example`. A standard implicit `ACTION_VIEW` launch of `/safety`
|
|
opened the native `MainActivity` and displayed the public Safety rules.
|
|
|
|
The manifest intentionally sets `android:autoVerify="false"`: this is a
|
|
same-origin HTTPS deep link, not a claimed verified Android App Link. Enabling
|
|
verification requires the final production application ID and signing
|
|
certificate fingerprint to be published in the deployment's
|
|
`/.well-known/assetlinks.json`.
|
|
|
|
A cross-client scenario then used headed Chrome as the requester and the
|
|
public-staging Android app as the helper. The observed behavior was:
|
|
|
|
- the Android app authenticated against the public HTTPS origin and rendered
|
|
the MapLibre request;
|
|
- chat messages travelled in both directions, including an Android-bound
|
|
browser message appearing without reload;
|
|
- Android granted foreground location permissions, started
|
|
`TrackingService`, and showed its persistent Stop notification;
|
|
- after Home minimized the Activity, an emulator location change from
|
|
`50.46009833, 30.5334` to `50.4611, 30.5344` reached PostGIS and produced
|
|
`121.97` metres of observed movement;
|
|
- the headed browser received the helper marker in real time and removed it
|
|
when tracking stopped;
|
|
- notification Stop removed the Android service and notification, ended the
|
|
exact tracking session, left zero active sessions, and deleted its raw current
|
|
position.
|
|
|
|
The browser scenario exposed one UI defect: movement evidence was persisted and
|
|
the marker updated, but the evidence badge remained stale until reload. The
|
|
tracking PubSub event now carries the already-derived movement/proximity
|
|
timestamps, and the LiveView updates its in-memory assignment from that same
|
|
event without an extra query. Domain and two-client LiveView regression tests
|
|
assert the event and badge change.
|
|
|
|
That fix was deployed with image digest
|
|
`sha256:1b991c1e07d98babb5151c010250cd0b9458195cf3de5a91972456ee72d75673`.
|
|
Both web and both worker containers used the digest, the cross-node PubSub probe
|
|
passed, local and public readiness returned HTTP 200, and no application
|
|
error/warning was found in the checked post-rollout logs. The before/after
|
|
database counts remained `2 users / 1 matched request / 7 messages / 14
|
|
categories / 1 assignment / 4 ended tracking sessions / 0 active tracking
|
|
sessions / 0 activities / 0 reports / 0 social identities`.
|
|
|
|
The exact temporary E2E users, tokens, request, assignment, messages, tracking
|
|
session, and audit records were removed in one scoped transaction. Queries by
|
|
their exact identifiers found no remaining rows and the original database
|
|
counts were restored. The headed browser windows and emulator were left open.
|
|
|
|
## Operations and metrics verification
|
|
|
|
On 2026-07-18, the Compose database was archived with PostgreSQL 18
|
|
custom-format `pg_dump`. The published archive and SHA-256 sidecar were
|
|
validated before an isolated restore. The restore drill created a database from
|
|
`template0`, restored with `pg_restore --exit-on-error`, read 23 public
|
|
application tables and 1106 restored rows, reported PostGIS 3.6.4, observed all
|
|
8 current migrations, and removed the exact temporary database. A follow-up
|
|
catalog query returned zero remaining restore-drill databases. Source counts
|
|
before and after remained `2 users / 1 help request / 7 messages / 14 categories
|
|
/ 1 assignment / 0 activities / 0 reports / 0 social identities`.
|
|
|
|
The same rollout started 2 healthy web replicas and 2 worker replicas. Local
|
|
live/readiness, public HTTPS readiness, and the public root returned HTTP 200.
|
|
The cross-node PubSub probe passed across all four connected BEAM nodes. The
|
|
protected metrics route returned HTTP 401 both locally and through public HTTPS
|
|
without credentials, returned valid Prometheus text with the generated ignored
|
|
local token, and was scraped directly from each web container. Helm 4.2.3 lint
|
|
and template rendering passed.
|
|
|
|
Before the runtime image change, every BEAM container logged that
|
|
`libsctp.so.1` was unavailable. The rebuilt Debian trixie release contains the
|
|
`libsctp1` package and the exact shared library; no SCTP, application error, or
|
|
application warning appeared in the post-rollout web/worker logs checked during
|
|
this verification window.
|
|
|
|
## Final full-stack regression
|
|
|
|
After isolating the load-test Compose project from staging, the complete
|
|
regression was repeated against the final source on 2026-07-18:
|
|
|
|
- `./scripts/test.sh` rebuilt the test image and passed all 149 Phoenix tests;
|
|
`mix format --check-formatted` and `mix compile --warnings-as-errors` also
|
|
passed.
|
|
- The staging and load-test Compose configurations both rendered successfully.
|
|
Helm 4.2.3 lint and template rendering passed with the checked-in kind values.
|
|
- The public root, `/healthz/live`, and `/healthz/ready` returned HTTP 200.
|
|
The two health responses were served by different web nodes during the
|
|
observation. The four-node web/worker cluster also passed the cross-node
|
|
Phoenix PubSub probe.
|
|
- Headed Chrome loaded the public home and Safety pages, including all
|
|
fingerprinted assets, and redirected an anonymous `/requests` visit to login
|
|
with the expected flash. The browser reported zero console errors and zero
|
|
warnings. Existing browser windows were left open.
|
|
- Both Android Docker builds repeated their unit-test, lint, and APK assembly
|
|
stages. The debug and staging artifacts retained the documented SHA-256
|
|
hashes, and both lint reports had no nonzero error or warning summary.
|
|
`apksigner` verified the staging APK's v2 generic debug signature; `aapt`
|
|
confirmed package `org.whoneedhelp.mobile.staging`, SDK 24 through 37,
|
|
disabled cleartext, and the exact HTTPS staging host.
|
|
- The protected metrics endpoint returned HTTP 401 without a token and valid
|
|
Prometheus text with the generated ignored token. The checked 15-minute
|
|
web/worker/proxy log window contained no application error, warning, or SCTP
|
|
finding.
|
|
- The staging database remained at 2 users, 1 help request, 1 assignment, 7
|
|
messages, 14 categories, 4 ended tracking sessions, 0 active tracking
|
|
sessions, 0 activities, 0 reports, and 0 social identities.
|
|
|
|
## Known work before a public production launch
|
|
|
|
- Replace the temporary staging origin with the production-owned domain and
|
|
production-sign the Android app.
|
|
- Operate PostgreSQL/PostGIS with backups, recovery testing, and the required
|
|
availability model.
|
|
- Load-test representative data and traffic, then set measured pool, resource,
|
|
autoscaling, and action-limit policies.
|
|
- Add pagination or bounded loading where real measurements show that request,
|
|
chat, moderation, or leaderboard result sets require it.
|
|
- Publish jurisdiction-specific emergency contacts, privacy, retention,
|
|
prohibited-items, and voluntary-payment guidance after legal review.
|
|
- Create and configure a GitHub OAuth App, then exercise the real external
|
|
provider redirect/callback in a headed browser. Until then staging keeps the
|
|
provider disabled and manual links remain unverified.
|