The Cohort is an Arabic-first learning platform for Computer Science students.
It combines structured study material, quizzes, challenges, moderation workflows, support tickets, PWA capabilities, and AI-assisted educational flows.
- Overview
- Key Features
- Tech Stack
- Architecture
- Prerequisites
- Local Setup
- Environment Variables
- Available Scripts
- Security Posture
- Deployment
- Open Source Workflow
- Troubleshooting
- License
The project is built as a Vite + React + TypeScript frontend with Supabase for authentication and data access, plus Vercel serverless endpoints for secure backend operations.
The platform targets educational use cases where reliability, safety, and clear access control are important.
- Academic material browsing and subject-based navigation
- Quiz engine with challenge mode and scoring workflows
- Support ticket and messaging flow
- Admin dashboards for moderation and content operations
- PWA support, offline behavior, and push notifications
- AI-powered educational helpers through a secured backend route
- Frontend: React 18, TypeScript, Vite
- Styling: Tailwind CSS, Framer Motion
- Data and Auth: Supabase
- Serverless API: Vercel Functions
- Build and Tooling: TypeScript compiler, Vite bundler
Top-level structure:
- src
- src/pages: app pages and admin pages
- src/components: reusable UI blocks
- src/services: data and business operations
- src/utils: utility and security helpers
- src/lib: shared clients such as Supabase
- api: serverless endpoints for sensitive operations
- public: static assets
- supabase: SQL migrations and database evolution files
- Node.js 18+
- npm 9+
- Supabase project with required schema
- Vercel account for production deployment
- Clone the repository.
- Install dependencies.
- Create a local environment file from .env.example.
- Start development server.
Example commands:
npm install npm run dev
Use .env.example as the source of truth.
Frontend variables:
- VITE_SUPABASE_URL
- VITE_SUPABASE_ANON_KEY
- VITE_WEB3FORMS_ACCESS_KEY
- VITE_APP_VERSION
Serverless variables:
- SUPABASE_URL
- SUPABASE_ANON_KEY
- SUPABASE_SERVICE_ROLE_KEY
- GEMINI_API_KEY
- GOOGLE_API_KEY
- ALLOWED_ORIGINS
- APP_ORIGIN
- GEMINI_REQUIRE_AUTH
- CRON_SECRET
- REMINDER_DISPATCH_SECRET
Important:
- Never commit real secrets.
- Keep production secrets only in Vercel environment settings.
- Rotate keys immediately if exposure is suspected.
- npm run dev: start local dev server
- npm run build: type-check then build production bundle
- npm run preview: preview built output locally
Security controls implemented in this codebase include:
- Environment validation for required keys and URL formats
- Input validation and sanitization at service boundaries
- Role and authorization checks in protected flows
- Browser-side security middleware for common client protections
- Strict headers configured in vercel.json
- Dedicated disclosure guidance in SECURITY.md
For vulnerability reporting, follow SECURITY.md.
Production deployment targets Vercel.
Relevant files:
- vercel.json: rewrites, headers, cron schedule
- api/gemini.ts: secured AI endpoint
- api/reminder-dispatch.ts: scheduled reminder dispatch
Recommended deployment checklist:
- Configure all required environment variables in Vercel.
- Confirm Supabase URL and keys are correct.
- Run local build before pushing.
- Verify headers and cron behavior in deployed environment.
Before contributing, read:
Typical contribution flow:
- Fork repository.
- Create branch.
- Implement focused change.
- Run build and validate behavior.
- Open pull request with clear description.
Common startup issues:
- Missing environment variable errors:
- Ensure local env file contains all required fields from .env.example.
- Supabase URL validation error:
- Use HTTPS Supabase project URL in VITE_SUPABASE_URL.
- Build issues after dependency changes:
- Remove node_modules and reinstall dependencies.
This project is licensed under MIT. See LICENSE.