diff --git a/README.md b/README.md index 7c1726b..0cb4228 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,26 @@ It is not an emergency or medical service, does not prescribe or sell medicine, and does not process payments. A helper may publish an optional external thank-you link; money goes directly between users outside the platform. +## OpenAI Build Week 2026 + +Who Need Help was created during the OpenAI Build Week submission period. The +entrant supplied the real-world problem, product priorities, safety decisions, +and deployment constraints. Codex running GPT-5.6 (`gpt-5.6-sol`) was used to +turn those decisions into the Phoenix application, tests, deployment tooling, +documentation, and browser verification. Important product choices—voluntary +help, medicine-first scope, consent-based tracking, two-party handover, and no +platform payments—remain human decisions rather than model-generated policy. + +The deployed application does not call the OpenAI API and contains no OpenAI +API key. Optional category-review assistance runs only through the operator's +local Codex CLI authenticated with their ChatGPT subscription. + +- Codex session ID for `/feedback`: + `019f725d-87b5-79e1-8a9f-66e6eaffb35a` +- Public test build: +- [Devpost submission draft and demo script](docs/devpost-submission.md) +- [Implementation and verification evidence](docs/verification.md) + ## What is implemented - Phoenix 1.8 LiveView application with passwordless email magic links, @@ -304,12 +324,12 @@ an explanation. A partial pair is rejected at startup and by the production environment validator. The flow requests `openid email profile`, verifies the provider email claim, -uses state, nonce, and PKCE, and discards provider tokens. Google registration -creates a confirmed local account only after the user accepts the 18+ safety -terms. Google login works only for an identity already linked to that local -account. An existing local account is never merged merely because Google -returns the same email; sign in by email or password and connect Google from -the sudo-protected account settings page instead. Leave +uses state, nonce, and PKCE, and discards provider tokens. A new Google identity +continues to a safe registration-completion page and creates a confirmed local +account only after the user accepts the 18+ safety terms. A returning linked +identity signs in directly. An existing local account is never merged merely +because Google returns the same email; sign in by email or password and connect +Google from the sudo-protected account settings page instead. Leave `GOOGLE_OAUTH_BASE_URL` and the Google HTTP timeout variables empty outside the isolated protocol drill. diff --git a/docs/devpost-submission.md b/docs/devpost-submission.md new file mode 100644 index 0000000..abe8ca3 --- /dev/null +++ b/docs/devpost-submission.md @@ -0,0 +1,136 @@ +# Who Need Help — Devpost submission draft + +This document is a ready-to-copy draft for the OpenAI Build Week submission. +It separates verified project facts from actions that still require the +entrant's Devpost and YouTube accounts. + +## Registration and final submission checklist + +1. Personally confirm eligibility under the official rules: age of majority, + supported location, and none of the listed exclusions or conflicts. +2. Create a free Devpost account or sign in, confirm its email if requested, + open the event page, and select **Join Hackathon**. +3. Start the project submission and use the fields drafted below. +4. Record and upload a public YouTube demonstration shorter than three minutes, + with clear audio and no unlicensed music or third-party marks. +5. Keep the repository private and grant access to + `testing@devpost.com` and `build-week-event@openai.com`, or make it public + only after the owner deliberately selects and adds a license. +6. Add the public YouTube URL, test-build URL, repository URL, and Codex + `/feedback` session ID; preview every field and submit before the deadline. + +Official references: + +- +- +- + +## Submission fields + +- **Project name:** Who Need Help +- **Track:** Apps for Your Life +- **Tagline:** Fast, local, voluntary help when every minute matters. +- **Demo build:** +- **Repository:** +- **Codex `/feedback` session ID:** + `019f725d-87b5-79e1-8a9f-66e6eaffb35a` +- **YouTube demo:** not uploaded yet +- **Built with:** Elixir, Phoenix 1.8, LiveView, PostgreSQL/PostGIS, Oban, + MapLibre, Docker Compose, Helm, Kotlin/Android, Codex, and GPT-5.6. + +## Description + +Who Need Help connects a person with an urgent, non-emergency need to a nearby +volunteer. Its first use case is medicine pickup: when a pharmacy or ordinary +delivery service cannot deliver in time, a volunteer can coordinate the pickup +and handover. The same data-driven flow already supports fuel, wheel, bicycle, +motorcycle, vehicle-breakdown, and secured-road-incident help without turning +the product into a marketplace or emergency service. + +The requester creates a categorized request and initially exposes only an +approximate area. A volunteer accepts it, then both people coordinate in a +private real-time chat. The requester can opt into live location sharing for +the active match. A one-time handover code and confirmation by both parties +complete the request. Double-blind reviews, unique-counterpart reputation, +blocking, scoped reports, and optional movement evidence reduce trivial rating +manipulation without pretending to provide guaranteed identity verification. + +The platform is free and does not process payments. A helper may publish an +optional external thank-you link after completion, but any transfer happens +directly between users. It is not a medical, pharmacy, emergency, transport, +or payment service. + +The architecture is intentionally extensible. Categories and their validated +fields live in PostgreSQL, and users can propose and vote on missing categories +for human moderation. Social activities—coffee, cinema, walks, and hikes—use a +separate lifecycle and never affect urgent-help reputation. The same immutable +release can run compactly on one server with Docker Compose or scale into +separate web and worker replicas and a later Kubernetes deployment. + +## How Codex and GPT-5.6 were used + +The entrant brought the problem, priorities, policy decisions, domain access, +and deployment constraints. Codex running GPT-5.6 (`gpt-5.6-sol`) helped turn +that direction into working software: Phoenix contexts and LiveViews, +PostGIS-backed location handling, real-time messaging, safety and privacy +controls, an Android client, Docker/Helm operations, automated tests, and the +verification documentation. + +Codex was also used as an engineering reviewer. It inspected the code and +queries, ran the test/security/performance gates, drove two independent headed +browser sessions through the end-to-end workflow, checked persisted database +effects, and repaired defects found during verification. One concrete example: +blocking correctly rejected chat messages on the server, but the blocked +request page still rendered a message form. The browser audit exposed that UX +gap; the LiveView now hides the form, shows an explicit blocked state, and has +a regression test. + +The application itself does not call the OpenAI API and does not require an +OpenAI API key. Its optional category-review tool runs only through the +operator's local ChatGPT-authenticated Codex CLI and receives a PII-free export. + +## Judge access + +The public test build does not require payment or a private network. Two +dedicated test accounts exercise requester and helper roles; their credentials +are stored outside Git in `output/devpost-testing-instructions.txt` and should +be copied into Devpost's private testing-instructions field. Test email is +captured by the isolated test Mailpit and is not a production delivery claim. + +## Demonstration script (target: 2 minutes 45 seconds) + +- **0:00–0:18 — Problem.** Explain the late medicine-pickup scenario and that + this is voluntary non-emergency coordination, not a pharmacy or courier. +- **0:18–0:42 — Create.** Register or sign in as the requester, create a + medicine request, show category-specific fields and approximate-area privacy. +- **0:42–1:05 — Match.** In the helper browser, discover and accept the request; + show both browsers updating and exchange one private chat message. +- **1:05–1:28 — Track.** Start consent-based location sharing, move the helper + marker, and point out that raw current positions are removed when sharing + stops. +- **1:28–1:52 — Verify.** Enter the handover code, confirm from both accounts, + submit double-blind reviews, and show the helper leaderboard. +- **1:52–2:15 — Extend and protect.** Briefly show category proposals, Activity + mode, privacy settings, block/report controls, and support/removal forms. +- **2:15–2:38 — Engineering.** Show one Compose deployment, separate web/worker + roles, PostgreSQL/PostGIS, the passing test count, and the verification doc. +- **2:38–2:45 — Codex.** State that Codex with GPT-5.6 implemented and audited + the project with the entrant, then show the public test URL. + +## Verified evidence and remaining external actions + +The current test release passed 286 Phoenix tests. A headed two-account browser +run completed registration, request creation, matching, chat, two-point live +tracking, tracking cleanup, handover, both-party completion, double-blind +reviews, leaderboard, privacy persistence, category proposal/vote, Activity +approval/chat/completion, message-scoped reporting, and block/unblock behavior. +The regression found during that run was fixed, retested in the browser, and +committed. + +The following are intentionally not claimed complete: + +- the public YouTube demonstration has not been recorded or uploaded; +- Devpost registration, eligibility confirmation, repository access sharing, + and the final submission have not been performed; +- production promotion is separate from the tested deployment and requires + explicit owner authorization. diff --git a/docs/verification.md b/docs/verification.md index d2062c4..f2675ed 100644 --- a/docs/verification.md +++ b/docs/verification.md @@ -28,6 +28,25 @@ results from product limits and unknown production properties. ## Reproducible checks +- On 2026-07-21, commit `437650d5e2c376b7e4254265c022fff67bbafb6f` + was deployed only to `https://test.whoneedhelp.com`. Two independent headed + Chrome contexts registered dedicated requester and helper accounts and + completed the medicine-request lifecycle: validated creation, discovery, + acceptance, realtime chat, start, two consented location samples, realtime + marker movement, tracking stop and raw-position cleanup, handover code, + both-party completion, double-blind reviews, and leaderboard update. The same + run verified privacy-setting persistence, category proposal/vote, Activity + creation/join approval/private chat/exact-location disclosure/completion, + message-scoped reporting, and block/unblock behavior. Read-only database + checks confirmed two tracking samples, 175.73 metres of aggregate movement, + no active tracking session or stored current position after stop, and review + reveal only after both reviews existed. A blocked conversation still rendered + its form even though the server rejected the message; that defect was fixed, + covered by a regression test, redeployed only to test, and browser-rechecked. + The Dockerized Phoenix suite passed 286 tests, format checking passed, and + both clean password logins were repeated in fresh headed browser contexts + with zero console errors or warnings. Production remained on commit + `4f2a9aaacc8eca606f3287df5c8663be49f9595b` throughout this verification. - On 2026-07-21, commit `811ddf4c5c3847fbb0c2861e6e72fcd6a9bd91fe` was deployed only to `https://test.whoneedhelp.com`. Headed Chrome attached to the user's existing dev-port profile completed real Google authorization,