Matcha

Matcha is a dating-oriented social web application from the 42 curriculum. People build a profile with photos, preferences, and location; they discover others through browse and search, send likes, and when both sides like each other they match and can talk in real time. The repo also ships an optional Laverna process—a scripted second account that drives the same flows and, after a match, can reply in chat using an LLM (Gemini) for demos and testing. Backend: @zolfagharipour. Frontend: @LuckyIntegral.

Stack and how the pieces connect are summarized under System overview below.

---

Warning for 42 Students

This repository is intended as a reference and educational tool. 42 students are strongly advised not to copy this code without fully understanding its functionality. Plagiarism in any form is against 42's principles and could lead to serious academic consequences. Use this repository responsibly to learn and better understand how to implement similar functionalities on your own.

---

Capabilities

• User authentication (JWT, cookies), email verification, password reset, email change
• Profiles, photos, geolocation, discovery, browse, search
• Realtime chat and notifications (Socket.IO)
• Optional Laverna process: automated user; Gemini-based replies in chat after mutual matches

---

System overview

HTTP and WebSocket traffic are handled in one Node process (server): Fastify serves the REST API under /api; Socket.IO shares the same origin for realtime (separate listen port from env). The Next.js app and the optional Laverna bot both call that API and open Socket.IO connections as clients. MySQL is the only durable store. @matcha/shared holds Zod-derived JSON schemas and shared types consumed at build time by client and server (not a runtime service).

flowchart TB
  subgraph clients [Clients]
    Web[Next.js]
    Bot[Laverna]
  end
  subgraph backend [server package]
    REST[Fastify REST]
    RT[Socket.IO]
  end
  DB[(MySQL)]
  Web -->|"HTTP cookies /api"| REST
  Web -->|WebSocket| RT
  Bot -->|HTTP REST client| REST
  Bot -->|WebSocket| RT
  REST --> DB
  RT --> DB

Loading

---

Local development

The project is intended to run in a Dev Container (MySQL and tooling are provided there).

Requirements: Docker; VS Code or compatible editor with the Dev Containers extension.

1. Open the repository in the editor and run Dev Containers: Reopen in Container. Wait for the image build. Dependency install runs on attach.
2. Copy .env.example into server/.env and client/.env. Set secrets (see comments in .env.example). Database user and password must match .devcontainer/start-dev.sh (matcha, app, app_pw_change_me).
3. Run pnpm dev. Default ports: 3000 (web), 5000 (HTTP API), 5001 (Socket.IO).

Optional: Sentry — set NEXT_PUBLIC_SENTRY_DSN in client/.env; for source maps at build time, use a local gitignored client/.env.sentry-build-plugin with SENTRY_AUTH_TOKEN. Optional Laverna: copy the Laverna block from .env.example to laverna/.env, then pnpm dev:laverna.

Adjusting the container (extensions, rebuild): docs/devcontainer.md.

---

Scripts (repository root)

Command	Effect
pnpm dev	Start client and server
pnpm build	Build shared, server, client
pnpm db:reset	Reset database (executed in server/)
pnpm dev:laverna	Run Laverna in development
pnpm lint	Lint
pnpm prettier	Format

---

Additional documentation

Document	Contents
server/README.md	Backend: features (domain + security), file structure, database
client/README.md	Frontend: application layout
laverna/README.md	Laverna: behavior and operation sequence
docs/devcontainer.md	Dev Container customization

---

Deployment

Production URLs must be consistent across CORS_ORIGIN, SERVER_URL or BASE_URL, CLIENT_URL, and client NEXT_PUBLIC_* variables. The Socket.IO endpoint must match NEXT_PUBLIC_SOCKET_URL or your proxy configuration.

---

External references

Next.js · Fastify · Socket.IO · Tailwind CSS