Skip to content

Repository files navigation

MeisterMatch

An interpretable, human-in-the-loop platform for matching skilled tradespeople with employers and clients in Latvia.

Next.js React TypeScript Tailwind CSS Supabase Python License: MIT

Bachelor's thesis project · Riga Technical University


Table of Contents


Overview

MeisterMatch connects homeowners and businesses with verified, reliable tradespeople — electricians, plumbers, welders, carpenters, HVAC technicians, and more — across Riga, Jūrmala, Liepāja, and Pierīga.

The platform explores data-driven matchmaking for the Latvian labour market using a transparent, interpretable ranking engine. Unlike black-box recommenders, every match exposes its reasoning: skill overlap, district proximity, hourly-rate fit, availability, and experience contribute to a human-readable match score.

This repository contains two related artefacts:

Artefact Description Status
meistermatch-web/ Next.js web application (frontend + Supabase backend) Actively maintained, used for live testing
meistermatch_prototypes/meistermatch-platform/ Three-tier research prototype (React/Vite + Express + FastAPI) Documented in thesis Chapter 3

Note: The two implementations are separate. The current web app lives in meistermatch-web/; the three-tier system described in Chapter 3 lives in meistermatch_prototypes/meistermatch-platform/.


Screenshots

Landing page

MeisterMatch landing page

Tradesperson directory

Search and filter tradespeople

Swipe-based matching

Swipe deck with interpretable ranker card
Sign up
Sign up with role selection
Log in
Log in

Features

  • Dual-mode discovery — browse a filterable directory or use a swipe-based deck to find tradespeople.
  • Interpretable recommendation engine — rule-based, multi-factor ranking (skills, district, availability, pay, experience) with human-readable reason strings and a visible match score.
  • Reciprocal matching — mutual interest unlocks a direct chat channel; matches persist to Supabase.
  • Meister onboarding — tradespeople register with trade, skills, district, location, hourly rate, and availability.
  • Role-based dashboards — distinct experiences for clients and Meisters, with session guards on protected routes.
  • Transparent pricing — hourly rates and typical job costs shown up front.
  • Graceful degradation — the UI falls back to deterministic seed data when the backend is unreachable, so the prototype always runs.
  • Research-grade evaluation — an active-learning ranker with offline experiment harness comparing against a fixed-weight baseline.

Repository Structure

Meistermatch-platform/
├── meistermatch-web/                     # Next.js app (current prototype)
│   ├── src/app/                          # App Router pages (landing, search, swipe, chat, portal, auth)
│   ├── src/lib/                          # Supabase client, auth bridge, schema SQL
│   └── public/                           # Static assets
├── meistermatch_prototypes/
│   └── meistermatch-platform/            # Three-tier thesis prototype (Chapter 3)
│       ├── web/                          # React + Vite frontend
│       ├── api/                          # Node + Express API (+ vitest/supertest test suite)
│       ├── ml/                           # FastAPI ranking service + active-learning experiments
│       └── shared/                       # JSON Schema contract + TS/Pydantic types
├── thesis_work/                          # Thesis manuscript, reports, and defence presentation
├── screenshots/                          # Platform screenshots used in this README
└── README.md

Tech Stack

meistermatch-web/ — current prototype

Layer Technology
Framework Next.js 16 (App Router)
UI React 19, TypeScript (strict), Tailwind CSS v4, Lucide icons
Backend / DB Supabase (PostgreSQL + Auth + Realtime)
Tooling ESLint, Next.js Turbopack

meistermatch_prototypes/meistermatch-platform/ — Chapter 3 prototype

Layer Technology
Frontend React 19 + Vite + TypeScript (:5173)
API Node.js + Express + TypeScript (:3001)
Ranking service Python + FastAPI (:8001)
Contract JSON Schema + TypeScript + Pydantic types
Data Deterministic synthetic seed (30 workers + 20 jobs)

Getting Started

Prerequisites

  • Node.js ≥ 18 and npm ≥ 9
  • Python ≥ 3.11 (only for the FastAPI ranking service)
  • A Supabase project (free tier is sufficient)

meistermatch-web/ (current app)

git clone https://github.com/AumSohoni/Meistermatch-platform.git
cd Meistermatch-platform/meistermatch-web
npm install

Create a .env.local file in meistermatch-web/:

NEXT_PUBLIC_SUPABASE_URL=your-supabase-project-url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-supabase-anon-key

Run the development server:

npm run dev
# open http://localhost:3000

meistermatch_prototypes/meistermatch-platform/ (three-tier prototype)

Requires three services running together (or use the provided start-all.ps1):

# Terminal 1 — FastAPI ranking service
cd meistermatch_prototypes/meistermatch-platform/ml && python main.py   # :8001

# Terminal 2 — Express API
cd meistermatch_prototypes/meistermatch-platform/api && npm run dev     # :3001

# Terminal 3 — Vite frontend
cd meistermatch_prototypes/meistermatch-platform/web && npm run dev     # :5173

See meistermatch_prototypes/meistermatch-platform/ARCHITECTURE.md for details.


Supabase Setup

Provision the database by running the schema file in your Supabase project's SQL Editor:

meistermatch-web/src/lib/supabase-schema.sql

This creates the profiles, jobs, swipes, matches, and messages tables and seeds sample data. If email confirmation is enabled in your Supabase Auth settings, new users must confirm their email before their first login.


Testing & Verification

meistermatch-web/ — lint, typecheck, build

cd meistermatch-web
npm run lint      # ESLint
npm run build     # production build + TypeScript type checking

meistermatch_prototypes/meistermatch-platform/api/ — automated API tests

The Express API ships an automated suite (Vitest + Supertest) covering all endpoints, including authentication and negative cases:

cd meistermatch_prototypes/meistermatch-platform/api
npm test          # 20 tests across the full API surface
npm run typecheck # tsc --noEmit

Ranking experiments

The active-learning ranker can be evaluated offline against a fixed-weight baseline:

cd meistermatch_prototypes/meistermatch-platform/ml
python experiment.py --run-self-checks

This reproduces the chapter's Precision@2 / NDCG comparisons across three market sizes.


AI Tool Disclosure

AI coding assistants were used during development of this project. A GEMINI.md file in the repository root records the engineering and design standards applied with AI assistance.

In line with Riga Technical University policy, any required disclosure of AI tool use is included in the thesis document (declarations / acknowledgments section) before submission.


Thesis Documentation

All thesis-related material is located in thesis_work/:

  • Bachelor_Thesis/ — manuscript chapters, the 6th-semester report, and the pre-defence presentation
  • Research_papers/ — supporting literature

Contributing

  1. Fork the repository.
  2. Create a feature branch: git checkout -b feature/your-feature.
  3. Commit your changes with clear messages.
  4. Open a pull request targeting master.
  5. Ensure npm run lint and npm run build pass.

License

This project is licensed under the MIT License — see the LICENSE file for details.


Acknowledgments

Special thanks to my supervisors, the RTU research committee, and the open-source community behind Next.js, React, Supabase, FastAPI, and the many libraries that made this work possible.

Prepared for academic evaluation and open-source sharing.

Releases

Packages

Contributors

Languages