QA-reviewed prototype for the DDISA Cohort 1 grantee directory.
This package is a developer handoff for the reviewed front-end workflows and a
local reference server. It is not yet a production Supabase deployment. See
DEVELOPER-HANDOFF.md for the required production work and QA-REPORT.md for
the release test results.
DDISA - Grantee Directory.html— application source.DDISA - Developer Prototype.html— self-contained interactive prototype with developer shortcuts.DDISA - Grantee Directory - Shareable.html— self-contained read-only copy for offline circulation.assets/— organisation logos and profile images used by the source build.server/— local reference server for API, validation and Supabase Auth session checks.supabase/— SQL schema, RLS policies and storage buckets for the database.scripts/— build, seed and private-link utilities.tests/— automated regression checks.
Create the local environment file and start the reference server:
cp .env.example .env
npm startOpen http://localhost:3000. Preview submissions are written under .data/.
- Run
supabase/schema.sqlin the Supabase SQL editor. It creates the tables, RLS policies and storage buckets described inDEVELOPER-HANDOFF.md. - Run
supabase/seed.sqlnext. It inserts all 46 Cohort 1 organisations with their Type of CSO, offering and social-link rows, and it is safe to re-run. The file is generated from the embedded directory source — if the HTML data ever changes, regenerate it withnpm run build:seed. - Upload the images:
npm run upload:assetscopiesassets/logos/andassets/profiles/into the storage buckets at the exact paths the seed writes intologo_path/photo_path(add--dry-runto preview). Until this runs, profiles will show broken images instead of the local assets. - Copy
.env.exampleto.env, fill inSUPABASE_URLandSUPABASE_SERVICE_ROLE_KEY, and start the server. When both values are present the server runs in Supabase mode; otherwise it falls back to local preview storage.DB_MODEcan force either mode.
Keep the service-role key on the server only. RLS allows the public anon key to read published rows and nothing else.
Supabase Auth is not wired up yet: grantee edit access still uses signed, expiring links, and authentication can be added on top later.
The deploy has two parts:
netlify/— the static site: the Grantee Directory front-end with the embedded dataset removed, loading published profiles directly from Supabase with the anon key.functions/— the server-side write flows (grantee sign-in, submissions, collaboration requests) running as Netlify Functions with the service-role key.
Connect this repository to Netlify (netlify.toml builds netlify/ and
registers functions/ automatically), then set Site settings →
Environment variables:
| Variable | Used by | Purpose |
|---|---|---|
SUPABASE_URL |
build + functions | Project URL (Supabase → Settings → API) |
SUPABASE_ANON_KEY |
build → config.js |
Public read key for the browser |
SUPABASE_SERVICE_ROLE_KEY |
functions only | Server-side writes; never shipped to the browser |
TRELLO_BOARD_EMAIL |
functions + server | Trello list's "Upload by email" address — forwards tickets with no API keys |
Trigger a deploy so the build injects the anon key into config.js. Then run
npm run upload:assets once from your machine so the seeded
logo_path/photo_path values resolve to real objects in Supabase Storage.
(Connecting the repo matters: drag-dropping netlify/ gives you the read-only
site only — the functions directory lives outside it.)
Row-level security keeps the browser's anon key read-only; every write is validated inside a Netlify Function before it touches the database.
npm run build:shareable
npm run build:developer-prototypeBoth builds embed all images so the resulting HTML files can be opened without
the assets/ directory.
Every organisation has a standalone, shareable profile page at
/org/<slug> — e.g. /org/digital-woman-uganda. Clicking an organisation
card navigates there on the deployed site, while the card's View button
opens the same profile in a quick-view modal. The page shows the same
profile content as a full page with Back to
directory, Copy link and (when signed in) Edit your organisation
actions.
- Netlify:
netlify.tomlrewrites/org*toindex.html(client-side route); the reference server serves the directory HTML for/org/<slug>directly. - Old shared modal links (
…#?profile=Name) redirect to the canonical/org/<slug>page. - The self-contained shareable/
file://build keeps the modal flow, since static files have no server routes. - API, config and asset URLs are root-absolute so they resolve from nested
/org/…paths.
The Support Desk is a standalone page served at /support-desk
(DDISA - Support Desk.html):
- When signed in, the directory shows a Support desk button next to Edit your organisation. It deep-links to the form with the signed-in organisation's name, contact email, country and organisation type already filled in.
- The form posts to
POST /api/support-requests(reference server). On Netlify the same URL is rewritten to thesupport-requestsfunction bynetlify.toml. server/lib/support-desk.mjs(SupportDeskService) validates the request and stores the ticket. Preview mode (default) writes.data/support-requests.jsonand attachments to.data/support-attachments/. Production mode (SUPPORT_DESK_MODE=production) writes thesupport_requeststable, uploads attachments to the privatesupport-attachmentsbucket, forwards each ticket to Trello by email (Trello's "Upload by email" address — no API keys), sends the requester's confirmation through thesupport-confirmationEdge Function (Brevo — script insupabase/functions/) and posts to Slack — each outcome is recorded in the ticket'sintegrationsJSON.- The table and bucket are created by
supabase/schema.sql(section 12). GET /api/support/healthreports the current mode and which integrations are configured.
Email secrets are set in Supabase only (Edge Function secrets, not server/Netlify env); Trello needs one server env var instead of any keys:
supabase secrets set BREVO_API_KEY=... SUPPORT_EMAIL_FROM=... SUPPORT_EMAIL_REPLY_TO=...
# Netlify/env: the list's "Upload by email" address (Board → … → Upload by email)
TRELLO_BOARD_EMAIL=list-abc123@boards.trello.com/support-admin (DDISA - Support Admin.html) is the team's view of the
support queue:
- Lists every
support_requeststicket (newest first) with status filter, per-row status changes (Received / In progress / Forwarded / Closed), Forward to Trello (idempotent — emails the card to the board's upload-by-email address), a full detail dialog, a signed one-hour attachment link, and a mailto: pre-filled with the ticket number. - Sign-in uses the same passwordless Supabase Auth flow and the same
browser session as the directory (
ddisa.auth). - Organisation logins: link any Supabase login email to an organisation from the Organisation logins table (the account is created automatically if it doesn't exist) so that person edits the profile with the directory's passwordless sign-in.
- Support admins can edit every organisation: the Edit button appears on
every profile, quick-view modal and
/org/<slug>page — the submission carries the targetorganisationIdand the server resolves it throughsupport_admins. - Organisation logins table: each row has Edit (opens the profile
straight in the editor via
/org/<slug>?edit=1), Set login / Unlink, and the section header has Add organisation — a small dialog (name, profile address, country, region, cohort, summary) that creates a published row through thecreate-orgadmin action and jumps to the new profile's editor to fill in the rest. - Authorization = membership of
public.support_admins. Grant access with (run after creating the user in Authentication → Users):
insert into public.support_admins (user_id, email)
select id, email from auth.users
where lower(email) = 'you@example.org'
on conflict (user_id) do nothing;Revoke by deleting the row (deleting the auth user cascades).
- API:
GET /api/support-admin(tickets),GET …?ticket=<id>(signed attachment URL),POST … {action:'status'|'forward', …}— all require the admin'sAuthorization: Bearer <jwt>(401 without a session, 403 without membership). On Netlify these rewrite to thesupport-adminfunction.
Production mode needs only the Supabase variables — Trello and Slack are
optional (their integrations entries report not configured until set),
and email needs no server env at all because the Edge Function holds the
Brevo secrets.
npm run qaThis validates source syntax, runs all automated tests and rebuilds both self-contained HTML files.
Grantees edit their profile by signing in with a Supabase Auth account — no expiring links, no passwords (email code / magic link):
- Create a user in Supabase → Authentication → Users → Add user (email only — no password needed; disable "Auto Confirm" if you want to vet sign-ups).
- Link that user to one organisation:
update organisations set owner_id = '<auth-user-uuid>' where slug = '…'; - Send the grantee your site URL with
?edit(e.g.https://ddisa.netlify.app/?edit) — or they click Grantee sign in in the directory header.
One-time Supabase Auth setup:
- Authentication → Email Templates → Magic Link: include
{{ .Token }}in the template so the email shows a 6-digit code the grantee can type into the sign-in dialog (the default template only has a link — clicking that works too; both paths are supported). - Authentication → URL Configuration: set Site URL to your deployed
origin (e.g.
https://ddisa.netlify.app) and addhttp://localhost:3000under Redirect URLs for local development — this is where magic links send the browser back.
How it holds together:
- The browser requests a one-time code from Supabase GoTrue
(
POST /auth/v1/otp) or the grantee clicks the emailed magic link; either way the session lands inlocalStorage, refreshing the JWT automatically. - Every editing request carries
Authorization: Bearer <jwt>. The site validates it viaGET /.netlify/functions/accessand reveals Edit your organisation for the organisation linked throughorganisations.owner_id. - Publishes flow through
POST /.netlify/functions/submissions, which re-verifies the session, validates every field server-side, uploads images to Storage, replaces the profile rows and records an audit row insubmissions. - Revoke access by deleting the user in Supabase → Authentication, or by
clearing
owner_id:update organisations set owner_id = null where slug = '…'; - New organisations (the Add your organisation form) and collaboration requests stay anonymous — no sign-in required — and go through the same functions, rate limited per connection, with the collaboration consent flag stored.
Local full-stack testing: npm start (reference server, shared submission
code) or npx netlify dev to run the real functions (needs netlify-cli).
Not yet connected: e-mailing collaboration notifications, Turnstile bot protection.
The included Node server mirrors the production write flows — direct
publication in Supabase mode, a local review queue in preview mode — and
verifies grantee sessions against Supabase Auth. It validates Type of CSO,
countries, offerings, contacts, resources, URLs and 5 MB image limits before
anything reaches the database; the Netlify Functions share that exact code
(server/lib/submissions.mjs).
The agreed production architecture is Supabase with automatic publication.
The adapter in server/lib/supabase-store.mjs implements the contract
described in DEVELOPER-HANDOFF.md against the schema in
supabase/schema.sql. There is no Docker or NocoDB dependency; the server
runs directly on Node and is intended to move behind Netlify Functions.
- Keep the service-role key server-side; only the anon key reaches the browser.
- Use HTTPS in production.
- Restrict static serving to the supplied HTML files and
/assets/. - Verify Supabase Auth sessions and all submitted fields on the server.
- Add bot protection to public submission endpoints.
- Do not publish
.env, database exports or storage credentials.