Matcha

Matcha is a full-stack dating application designed to connect users based on intelligent matching criteria. This project is built as a micro-framework implementation, avoiding heavy ORMs and monolithic structures in favor of cleaner, raw SQL queries and modular architecture.

🚀 Key Features

• User Management:

  • Secure registration and login flows.
  • Email verification and password reset functionality.
  • Google OAuth integration.
  • Comprehensive profile management (Bio, Gender, Sexual Preference, Tags, Photos).
  • GPS Localization (with manual override).

• Smart Matching:

  • Algorithm: Prioritizes matches based on:
    1. Geolocation: Proximity using the Haversine formula.
    2. Common Interests: Shared tags overlap.
    3. Fame Rating: Popularity metric based on user interactions.
  • Filtering: Advanced search filters for Age, Distance, Fame, and Tags.

• Real-time Interactions:

  • Chat: Instant messaging with connected users (mutual likes), powered by WebSockets.
  • Notifications: Live alerts for Likes, Visits, Messages, Matches, and Unlikes.
  • Privacy: Block and Report functionality to maintain a safe environment.

🛠️ Technology Stack

Backend

• Language: Python
• Framework: Flask (Micro-framework)
• Database: PostgreSQL (Schema & Migrations)
• Database Access: psycopg2 (Raw SQL, No ORM)
• Authentication: JWT (JSON Web Tokens)
• Real-time: Flask-SocketIO

Frontend

• Framework: React (Vite)
• Routing: TanStack Router
• State Management: TanStack Query
• Styling: Tailwind CSS
• Real-time Client: socket.io-client

🏗️ Project Structure

matcha/
├── backend/             # Flask Backend
│   ├── app/
│   │   ├── blueprints/  # Route handlers (Auth, Profile, Chat, etc.)
│   │   ├── sockets/     # WebSocket event handlers
│   │   └── utils/       # Utility functions (Fame calc, Email, Validation)
│   ├── schema/          # Database schema and migrations
│   └── scripts/         # Seeding and migration scripts
├── frontend/            # React Frontend
│   └── src/             # Components, Hooks, API integration
├── database/            # Database configuration (Docker)
└── doc/                 # Project documentation

⚡ Getting Started

Prerequisites

• Docker & Docker Compose

Installation & Run

1. Clone the repository:

   git clone <repository-url>
   cd matcha

2. Start the services:

   make fresh
   # OR manual docker command:
   docker-compose --env-file ./backend/.env up --build -d

   This will spin up:

   • Frontend: http://localhost:3000
   • Backend: http://localhost:5000
   • PostgreSQL: localhost:5432

3. Seed the Database (Optional): To populate the app with 500+ fake users for testing:

   make seed
   # OR manual command:
   docker exec -it matcha_backend python scripts/seed.py --count 500 --clear

🧪 Testing

The project includes manual test scenarios aligned with the subject requirements. Check doc/correction_page.md for the detailed evaluation checklist.

🔒 Security

• Passwords hashed with Bcrypt.
• SQL Injection prevention using Parameterized Queries.
• Input validation for all forms and uploads.
• Secure JWT authentication.

---

Built with ❤️ for the 1337 / 42 Network Matcha Project.