An interpretable, human-in-the-loop platform for matching skilled tradespeople with employers and clients in Latvia.
Bachelor's thesis project · Riga Technical University
- Overview
- Screenshots
- Features
- Repository Structure
- Tech Stack
- Getting Started
- Supabase Setup
- Testing & Verification
- AI Tool Disclosure
- Thesis Documentation
- Contributing
- License
- Acknowledgments
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 inmeistermatch_prototypes/meistermatch-platform/.
- 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.
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
| 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 |
| 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) |
- Node.js ≥ 18 and npm ≥ 9
- Python ≥ 3.11 (only for the FastAPI ranking service)
- A Supabase project (free tier is sufficient)
git clone https://github.com/AumSohoni/Meistermatch-platform.git
cd Meistermatch-platform/meistermatch-web
npm installCreate a .env.local file in meistermatch-web/:
NEXT_PUBLIC_SUPABASE_URL=your-supabase-project-url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-supabase-anon-keyRun the development server:
npm run dev
# open http://localhost:3000Requires 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 # :5173See meistermatch_prototypes/meistermatch-platform/ARCHITECTURE.md for details.
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.
cd meistermatch-web
npm run lint # ESLint
npm run build # production build + TypeScript type checkingThe 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 --noEmitThe active-learning ranker can be evaluated offline against a fixed-weight baseline:
cd meistermatch_prototypes/meistermatch-platform/ml
python experiment.py --run-self-checksThis reproduces the chapter's Precision@2 / NDCG comparisons across three market sizes.
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.
All thesis-related material is located in thesis_work/:
Bachelor_Thesis/— manuscript chapters, the 6th-semester report, and the pre-defence presentationResearch_papers/— supporting literature
- Fork the repository.
- Create a feature branch:
git checkout -b feature/your-feature. - Commit your changes with clear messages.
- Open a pull request targeting
master. - Ensure
npm run lintandnpm run buildpass.
This project is licensed under the MIT License — see the LICENSE file for details.
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.




