Circle (سيركل)

Bilingual (Arabic RTL / English LTR) marketing site for Circle — AI automation for dental clinics.

• Stack: Next.js (App Router) + Tailwind CSS v4
• Routes: /ar (default), /en
• Texts: src/i18n/ar.ts, src/i18n/en.ts
• Demo form (3 steps, clinic-specific) → POST /api/lead → Supabase leads table (+ optional n8n webhook)
• Contact number and WhatsApp links: src/lib/contact.ts

Environment

Variable	Purpose
SUPABASE_URL	Supabase project URL
SUPABASE_ANON_KEY	Supabase anon key (used server-side only; the browser never talks to Supabase)
SUPABASE_SERVICE_ROLE_KEY	Server-only key: inserts leads and creates accounts for accepted invitations. Never expose it
N8N_BOOKING_WEBHOOK_URL	Optional n8n webhook called after each booking (website or API, event appointment.booked, includes when and manage_url) — see n8n/
SITE_URL	Public site URL, e.g. https://circle.sa. Required in production: links and redirects are built from it (behind the proxy the app cannot see its public address)
N8N_LEAD_WEBHOOK_URL	Optional n8n webhook notified of each new lead
N8N_WEBHOOK_SECRET	Optional, sent as x-circle-secret header
RATE_LIMIT_SALT	Random secret used to hash client IPs for rate limiting (falls back to the service key)

Develop

npm install
npm run dev

Deploy: patient data must stay in Saudi Arabia (PDPL), so production runs self-hosted Supabase + this app + n8n on one VM in Oracle Cloud Jeddah (a Saudi region). Everything is scripted in deploy/ (install, updates, encrypted backups, restore, monitoring). Don't use hosted services outside KSA for patient data.

Launch checklist

npm run preflight -- --live https://your-site     # env, security, PDPL, cost caps + read-only probes

Every push runs CI (.github/workflows/ci.yml): types, lint, unit tests, SQL security tests, build.

Vercel (demo, fictional data only): import the repo, set the variables from .env.example (plus CRON_SECRET; vercel.json runs the daily ops check), and run supabase/setup.sql on the database. Production with real patients: the self-hosted kit in deploy/ (Jeddah), because patient data must stay in Saudi Arabia (PDPL).

Database

Run supabase/setup.sql (all migrations concatenated) in the SQL Editor, or the files in supabase/migrations/ in order. Upgrading an existing database: run only the migrations added since (every migration is safe to re-run).

Then in Supabase:

1. Authentication → Sign In / Providers → Email: turn off "Allow new users to sign up". Accounts are only created through invitations.
2. Make yourself a Circle admin: create your user in Authentication → Users → Add user, then run

   insert into public.platform_admins (user_id)
   select id from auth.users where email = '[email protected]';
   

3. Password reset (/ar/forgot): configure SMTP for Auth, and add {SITE_URL}/auth/callback to the allowed redirect URLs. The email link lands on /auth/callback, which opens /{lang}/reset-password.

Clinic portal (/ar/portal, /en/portal)

• Circle admin: sees all demo requests and clinics, activates a lead (creates the clinic + an owner invitation link to send on WhatsApp), sets status / plan.
• Clinic members: see only their own clinic. Roles: owner, manager, doctor, reception. Owners manage everyone; managers manage doctors and reception; doctors and reception are read-only.
• Doctors' board (جدول الأطباء): the day's appointments per doctor on a time axis, with off-hours; a doctor sees only their own column. Conversations (المحادثات): WhatsApp chats handled by the AI assistant, with take-over and replies for the front desk. Reports (التقارير, owners/managers): KPIs by period, doctor, service and source, CSV export, and an automatic weekly WhatsApp summary. Setup of the WhatsApp assistant and reports: n8n/README.md.

Security model

• Tenant isolation in Postgres: every table has RLS; policies call is_clinic_member / can_manage_clinic / can_assign_role, so a bug in the app cannot leak another clinic's data.
• Guards: triggers stop non-admins changing subscription fields, moving members between clinics, or removing a clinic's last owner. Every change is written to audit_log.
• Sessions: Supabase tokens live only in HttpOnly, Secure (in production), SameSite=Lax cookies; there is no Supabase client in the browser. src/proxy.ts refreshes sessions and guards /portal. Portal pages send Cache-Control: private, no-store and noindex.
• Invitations: 256-bit random tokens; only their SHA-256 is stored; single use; expire after 7 days; bound to the invited email.
• Rate limiting: lead form, booking, availability, sign-in, invitations, self-service links and the clinic API are limited per hashed IP (or API key) via rate_limit_hit in Postgres (src/lib/rate-limit.ts).
• Headers: HSTS, X-Frame-Options: DENY, nosniff, strict referrer and permissions policies.

Clinic data & public booking

20260926000000_clinic_data.sql adds each clinic's public site settings (clinic_sites: slug, template, brand, booking rules), branches, doctors, services, weekly working hours, time off, patients, clinical notes and appointments.

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