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: Gitea — version control
  • Branching model: main + develop + short-lived task branches
  • Versioning: Semantic Versioning (SemVer) — MAJOR.MINOR.PATCH
  • CI/CD platform: Gitea Actions
  • Work tracker: Trello (sprint planning/kanban) + Gitea Issues (per-PR/granular tracking) — see Team Links below
  • 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

See API Conventions for how the backend is actually structured — 9 independent services behind a gateway, not modules in one app — and the real request/response/error shapes in use.

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. Shared design tokens (colors, spacing, typography) live in styles/theme.css.

Vitest runs tests in milliseconds (faster than Jest), shares the same Vite config as your dev environment, and integrates seamlessly with React Testing Library.

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. Each backend service has its own Prisma schema and generated client, scoped to its own Postgres schema namespace within the shared Supabase instance.

Zod validates request bodies and route params before they reach a controller. 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 our hand-written Express APIs without forcing us to use Supabase's auto-generated data API. Auth is verified independently in every backend service via requireAuth (from the shared @osl/shared package), not centrally at the gateway.

node:test (Node's built-in test runner) is used across backend services rather than Vitest for backend tests, paired with real in-process Express servers for route-level tests. Services are built with a dependency-injection pattern (constructor-injected defaults) specifically so tests can substitute fakes without needing to mock live module bindings.

Docker​

Docker lets each team member run a backend service and its database identically, regardless of OS, and is the deployment model for Render. Building Docker images early prevents last-minute deployment surprises.

Husky + ESLint + Prettier​

Husky runs Git hooks (lint + format checks) on every commit, before they're even pushed. ESLint/Prettier (or oxlint, used in some workspaces) catch common mistakes and keep formatting consistent, so developers focus on logic, not style debates.

Cloudflare Pages + Render​

Cloudflare Pages deploys static assets globally, with automatic preview deploys on every PR, free for a project this size.

Render provides Node.js hosting with built-in Docker support and environment variable management — each of the 9 backend services deploys as its own Render service.

Supabase as our database saves us from provisioning Postgres ourselves — it handles backups, SSL, and scaling. We access it via Prisma over a connection string, never via Supabase's auto-generated REST API, per the brief's hand-written-API requirement.

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 on Gitea Actions, the automated pipeline stages, testing policy, 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.

🔌 API Conventions​

How every backend endpoint is wired, named, shaped, and reviewed — the real conventions in use, not an aspirational plan.

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.