CyberSafe

A cyber-safety platform for South African learners, built with C3SA (a non-profit). Learners can take short modules and quizzes, read scam guides, share and read moderated community reports, find emergency contacts, and chat with CyberBot on WhatsApp about cyberbullying and online scams.

Architecture

flowchart LR
  L[Learner on phone/browser] -->|HTTPS| W[Web app<br/>Next.js PWA<br/>Vercel]
  L -->|WhatsApp| M[Meta WhatsApp<br/>Cloud API]
  M -->|signed webhook| B[CyberBot<br/>Node/Express<br/>Render]
  B -->|chat completion| G[Groq API<br/>gpt-oss-120b]
  W -->|supabase-js<br/>anon key + user JWT| S[(Supabase<br/>Postgres + Auth + Storage<br/>Row Level Security)]
  A[Admin / teacher] --> W
  B -. "ask for a person" .-> C3[C3SA staff WhatsApp]

There is no separate application server. The web app talks to Supabase directly, and the database enforces who may do what:

• Row Level Security (RLS) on every table: learners see only their own progress, community posts are visible only once approved, and only admins can write content.
• Server-side functions for anything that must not be trusted to the browser:
  • submit_quiz() grades a quiz and is the only way progress is saved.
  • check_quiz_answer() reveals the correct answer for one question after it is answered.
  • admin_save_learning_content() saves a module and its quiz in one transaction.
  • validate_new_post() rejects reports that are too short or too long, or carry oversized images.
  • post_flags records "Report post" flags (one per person per post). Admins see them under the "flagged" filter in /admin/community.
  • set_post_display_name() sets a post's public name from the author's username, so it cannot be faked.
  • auto_hide_reported_post() returns a post to review after 3 reports.
  • post_like_counts is a view that gives public "helpful" counts without revealing who liked what.
  • is_admin() is the shared role check used by policies.
• Roles (learner, teacher, admin) live in profiles and cannot be changed from the browser.
• Guests (anonymous sign-in) can learn and use the library/help pages but cannot post or report. Guest progress belongs to that browser and is not carried over if the person later creates an account.

How the community feed is moderated

1. A signed-in learner (not a guest) writes a post in the feed or fills in the report form.
2. It is saved in posts with status pending. Only the author can see it, marked "Pending review".
3. A C3SA admin opens /admin/community, reads it, and approves or removes it.
4. Approved posts appear for everyone. Readers can mark a post helpful, share it, or report it.
5. When 3 different people have reported a post, the database sends it back to pending automatically. When an admin re-approves it, only new reports count.

The server enforces this, not just the screens: signed-out visitors cannot insert posts, nobody can approve their own post, and the public name is set from the author's username by the database (or "Anonymous" if they ticked that box). Admins can still see who wrote an anonymous post.

How comments are moderated

Comments work differently from posts, on purpose. A review queue for every reply would make a conversation unusable, so comments appear straight away and safety comes from other controls:

1. Only signed-in members (not guests or signed-out visitors) can comment, on approved posts only. Comments are 1 to 500 characters, and a person can post at most 10 in 10 minutes.
2. The public name is set by the database from the member's username, so it cannot be faked.
3. Readers can report a comment. When 3 different people have reported it, it is hidden automatically until an admin looks at it. When an admin restores it, only new reports count.
4. Admins moderate comments on the same page as posts: /admin/community, Comments tab. The default view is "Reported". They can restore, hide or remove a comment. Removed comments stay in the database for records.

Repository layout

Path	What it is
apps/web	Next.js 15 / React 19 web app (installable PWA). Pages are in src/app/*.
whatsapp-bot	CyberBot: Express webhook + Groq. index.js (server), bot-logic.js (AI + safety), commands.js (typed commands), security.js (webhook signature check), test/ (automated tests).
supabase	schema.sql (initial schema), migrations/ (dated changes), seed_*.sql (starter content).

Running it locally

1. Web app

cd apps/web
npm install
cp .env.example .env.local   # then fill in the two values below
npm run dev                  # http://localhost:3000

Variable	Where to find it
NEXT_PUBLIC_SUPABASE_URL	Supabase → Project Settings → API
NEXT_PUBLIC_SUPABASE_ANON_KEY	Supabase → Project Settings → API (the anon/public key only)

Without these the app still starts in a demo mode so the UI can be worked on.

This is the beginning of the README. Read the rest at the original. Read the full README ↗