Skip to main content

Open Source Languages — Team Handbook

Welcome! This is the single source of truth for how our 6-person team works together over the next 6 weeks.

Quick Facts
  • Repository: Git (GitHub/Gitea) — version control
  • Branching model: main + develop + short-lived task branches
  • Versioning: Semantic Versioning (SemVer) — MAJOR.MINOR.PATCH
  • CI/CD platform: GitHub Actions (or Gitea Actions)
  • Deployment: Cloudflare Pages (frontend) · Render (backend)

Tech Stack at a Glance​

  • Framework: React 18 + Vite
  • Language: TypeScript (strict mode)
  • Styling: CSS Modules
  • Testing: Vitest + React Testing Library
  • Linting: ESLint + Prettier
  • Pre-commit hooks: Husky
  • Deployment: Cloudflare Pages

Why We Chose These Tools​

Frontend: React + Vite + CSS Modules​

React + Vite is a lightweight, fast alternative to Next.js. Since our project brief explicitly requires a non-monolithic frontend and backend (separated deployables), we don't need Next.js's server-side rendering or API routes — Vite's pure client-side dev server is faster to iterate on and simpler to set up.

CSS Modules (scoped CSS per component) keep styles isolated and maintainable as the frontend grows. Unlike utility frameworks, modules avoid the "long class strings in JSX" problem and make it trivial to reason about which styles affect which component. This is especially valuable on a 6-person team where six people might otherwise invent six different styling patterns.

Vitest runs tests in milliseconds (faster than Jest), shares the same Vite config as your dev environment, and integrates seamlessly with React Testing Library. For a 6-week sprint where CI feedback speed matters, Vitest's instant test re-runs make iteration much faster.

Backend: Express + Typescript + Prisma + Zod​

Express.js is lightweight, battle-tested, and requires you to hand-write every endpoint — which is exactly what the brief demands ("hand-written API, not auto-generated"). This keeps you in control of the API shape and prevents the "Supabase data API temptation" that sneaks in when using lighter frameworks.

Prisma ORM eliminates raw SQL while staying explicit about queries. The schema file serves as both your type system and migration tool, reducing the mental overhead of keeping three things (types, DB, migrations) in sync. Prisma's query builder is also faster to debug than raw queries when something goes wrong.

Zod validates request bodies before they reach your controllers. It's lightweight, produces great error messages, and generates TypeScript types automatically — one source of truth for both runtime validation and compile-time types.

Supabase Auth is a managed, battle-tested authentication provider. The brief forbids hand-rolling auth ("you must rely on established practices and libraries"), and Supabase's JWT-based flow integrates cleanly with your hand-written Express API without forcing you to use their auto-generated data API.

Supertest makes API testing simple — no need to spin up a real server per test. It's the de facto standard for testing Express apps and integrates with Vitest trivially.

Docker​

Docker lets each team member run the backend and database identically on their machine, regardless of OS. The brief requires CI/CD, and Docker makes your CI pipeline reproducible (tests run in the same container as production). For Render deployment, Docker is also the deployment model — so building Docker images early prevents last-minute surprises.

Husky + ESLint + Prettier​

Husky runs Git hooks (lint + format checks) on every commit, before they're even pushed. This catches style violations and obvious bugs locally instead of letting them clog up CI.

ESLint catches common JavaScript mistakes (unused variables, incorrect type usage). Prettier auto-formats code, eliminating style debates ("should we use single or double quotes?") and keeping diffs clean.

Together, these three tools enforce consistency across a 6-person team and let developers focus on logic, not formatting.

Cloudflare Pages + Render​

Cloudflare Pages deploys static assets globally, with automatic branching for preview deploys on every PR. It's free for the use case (no server-side logic, just static files). The global CDN also means anyone testing your frontend gets decent latency.

Render provides Node.js hosting with built-in Docker support, environment variable management, and one-command deploy from GitHub. For a university project, Render's free tier is sufficient (you pay for what you use, starting at $0.10/hour for running services). It's also less fiddly than raw AWS or Azure for someone not deep in DevOps.

Supabase as your database saves you from provisioning Postgres yourself — Supabase handles backups, SSL, and scaling. You access it via Prisma over a connection string, never via their auto-generated REST API.

What's in this handbook​

🌱 Git Methodology​

Branching strategy, naming conventions, commit rules, Pull Request workflow, code review, merge strategy, and semantic versioning.

⚙️ CI/CD Strategy​

What CI/CD means for us, the automated pipeline stages, testing policy (Vitest + Supertest), coverage targets, and branch protection rules.

📋 Project Plan​

Complete development guide from kickoff to deployment — architecture, tech decisions, folder structure, coding standards, deployment strategy.

📖 User Stories & Sprints​

Feature breakdown by tier (Basic, Intermediate, Advanced), 4-sprint roadmap, exit criteria, and story IDs for tracking work.

The Golden Rule​

Never Do This

Never commit directly to main or develop. All work happens on a task branch and lands via a reviewed, passing Pull Request.

Daily Workflow at a Glance​

Use the sidebar to dive into each section. Start with Git Methodology and CI/CD Strategy if you're new to the team.

Key Dates​

MilestoneDateDeliverable
Week 1 complete+7 daysFoundation live, Basic tier architecture in place
Week 3 complete+21 daysBasic tier fully working and deployed
Week 5 complete+35 daysIntermediate tier fully working
Week 6 submission+42 daysFinal submission with Advanced tier (selected features)

Questions?​

Refer to the relevant doc in the sidebar, or ask your team lead.

Remember: This handbook is a living document. If something changes, we update it here so everyone stays in sync.