AI Matchmaker Web Platform

A modern, AI-powered matchmaking web application that uses multi-agent systems to facilitate meaningful connections through personality assessment and real-time compatibility analysis.

🚀 Features

• Interactive Personality Assessment: Comprehensive questionnaire to build detailed user profiles
• AI-Powered Matching: Advanced compatibility algorithms using personality data
• Live AI Conversations: Watch AI avatars interact in real-time to assess compatibility
• Relationship Simulations: AI agents navigate realistic scenarios to test long-term compatibility
• Real-time Communication: WebSocket-powered live updates and notifications
• Modern Web Interface: Responsive React application with Material-UI components
• Comprehensive Analytics: Detailed compatibility reports and insights

🏗️ Architecture

Frontend

• React 18 with TypeScript
• Vite for fast development and building
• Material-UI (MUI) for component library
• Redux Toolkit for state management
• Socket.IO for real-time communication
• Recharts for data visualization

Backend

• FastAPI with Python 3.11+
• PostgreSQL for relational data
• Redis for caching and sessions
• SQLAlchemy with async support
• WebSocket support for real-time features
• JWT authentication

AI & Agents

• AgentScope framework for multi-agent orchestration
• Google Gemini API for AI-powered conversations
• Mem0 for advanced memory management
• ChromaDB for vector storage

🛠️ Development Setup

Prerequisites

• Python 3.11+ for backend development
• Node.js 18+ for frontend development
• Remote PostgreSQL database access
• Remote Redis cache access

Quick Start (Windows)

1. Clone the repository

   git clone <repository-url>
   cd ai-matchmaker

2. Set up development environment

   scripts\setup-dev.bat

3. Configure environment variables

   • Edit .env file with your remote database URLs and API keys
   • Set DATABASE_URL to your PostgreSQL connection string
   • Set REDIS_URL to your Redis connection string
   • Set GEMINI_API_KEY to your Google Gemini API key

4. Start development servers

   scripts\start-dev.bat

5. Access the application

   • Frontend: http://localhost:3000
   • Backend API: http://localhost:8000
   • API Documentation: http://localhost:8000/docs

Manual Setup

1. Install dependencies

   # Backend
   py -m venv venv
   venv\Scripts\activate
   pip install -r requirements.txt
   
   # Frontend
   cd frontend
   npm install

2. Start development servers

   # Backend (in one terminal)
   cd backend
   py -m uvicorn main:app --reload --host 0.0.0.0 --port 8000
   
   # Frontend (in another terminal)
   cd frontend
   npm run dev

📋 Available Commands

Development

# Set up environment (Windows)
scripts\setup-dev.bat

# Start development servers (Windows)
scripts\start-dev.bat

# Manual start
make backend-dev     # Start backend only
make frontend-dev    # Start frontend only

Testing

make test             # Run all tests
make test-frontend    # Run frontend tests
make test-backend     # Run backend tests
make lint             # Run linting

Docker

make docker-build     # Build Docker images
make docker-up        # Start Docker services
make docker-down      # Stop Docker services
make docker-logs      # View logs

Database

make db-migrate       # Run database migrations
make db-reset         # Reset database

🧪 Testing

The project uses a comprehensive testing strategy:

Frontend Testing

• Vitest for unit testing
• React Testing Library for component testing
• ESLint for code quality

Backend Testing

• pytest for unit and integration testing
• Hypothesis for property-based testing
• pytest-asyncio for async testing

Run Tests

# All tests
make test

# Frontend only
cd frontend && npm run test

# Backend only
cd backend && python -m pytest tests/ -v

🚀 Deployment

Production Build

make build

Docker Production

docker-compose -f docker-compose.prod.yml up -d

Environment Variables

Key environment variables for development and production:

# Security
SECRET_KEY=your-production-secret-key
DEBUG=false
ENVIRONMENT=production

# Remote Database
DATABASE_URL=postgresql+asyncpg://user:pass@host:port/db

# Remote Redis
REDIS_URL=redis://user:pass@host:port

# AI Services
GEMINI_API_KEY=your-gemini-api-key

# File Storage (Optional)
AWS_ACCESS_KEY_ID=your-aws-key
AWS_SECRET_ACCESS_KEY=your-aws-secret
S3_BUCKET_NAME=your-s3-bucket

📁 Project Structure

ai-matchmaker/
├── frontend/                 # React TypeScript frontend
│   ├── src/
│   │   ├── components/      # Reusable UI components
│   │   ├── pages/          # Page components
│   │   ├── store/          # Redux store and slices
│   │   ├── hooks/          # Custom React hooks
│   │   └── theme/          # Material-UI theme
│   ├── public/             # Static assets
│   └── package.json
├── backend/                  # FastAPI backend
│   ├── app/
│   │   ├── api/            # API endpoints
│   │   ├── core/           # Core configuration
│   │   ├── models/         # Database models
│   │   └── websocket/      # WebSocket handlers
│   └── main.py
├── ai_matchmaker/           # Original AI agent system
│   ├── agents/             # AI agent implementations
│   ├── models/             # Data models
│   └── utils/              # Utilities
├── tests/                   # Test suites
├── scripts/                 # Deployment scripts
├── .github/workflows/       # CI/CD pipelines
├── docker-compose.yml       # Development environment
└── Makefile                # Development commands

🔧 Configuration

Frontend Configuration

• Vite config: frontend/vite.config.ts
• TypeScript config: frontend/tsconfig.json
• ESLint config: frontend/.eslintrc.cjs

Backend Configuration

• FastAPI settings: backend/app/core/config.py
• Database models: backend/app/models/
• API routes: backend/app/api/v1/

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Guidelines

• Follow TypeScript/Python type hints
• Write tests for new features
• Use conventional commit messages
• Ensure all tests pass before submitting PR

📄 License

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

🆘 Support

For support and questions:

• Create an issue in the repository
• Check the documentation
• Review the API documentation when running locally

🔮 Roadmap

• Mobile app development
• Advanced AI personality models
• Video chat integration
• Social features expansion
• Multi-language support
• Advanced analytics dashboard