Local Singles Date Night

Local Singles Date Night is a dating platform that flips the traditional model on its head: instead of paying for memberships or endless boosts, users pre-purchase a 1, 3, 5, or 10-dinner package from participating local restaurants and businesses.

🎯 Value Proposition

For Singles:

• Curated first-date experiences with local restaurants
• No endless swiping or chat fatigue
• Budget clarity with prepaid packages
• Safety features and verified profiles
• Real-world meetings with compatible matches

For Restaurants:

• Predictable prepaid revenue
• Demand smoothing on lower-traffic nights
• Turnkey co-marketing opportunities
• Reduced no-shows with prepaid bookings

🚀 Quick Start

Prerequisites

• Docker and Docker Compose
• Git

Local Development with Docker (Recommended)

1. Clone and setup:

   git clone <repository-url>
   cd LSDN

2. Start all services with Docker Compose:

   docker compose up -d

   This will start:

   • PostgreSQL with PostGIS (port 5432)
   • Redis (port 6379)
   • Backend API (port 3000)
   • Frontend (port 5173)

3. Seed the database with Santa Cruz demo data:

   docker compose exec backend npm run seed

4. Access the applications:

   • Frontend: http://localhost:5173
   • Backend API: http://localhost:3000
   • API Health: http://localhost:3000/health

5. Test credentials:

   • Email: sc.tester@example.com
   • Password: Password123!

Viewing Logs

# All services
docker compose logs -f

# Specific service
docker compose logs -f backend
docker compose logs -f frontend

Stopping Services

# Stop all containers
docker compose down

# Stop and remove volumes (fresh start)
docker compose down -v

🏗️ Architecture

Tech Stack

Backend:

• Node.js with Express.js
• TypeScript
• PostgreSQL with PostGIS
• Redis for caching
• Stripe for payments
• Cloudinary for image processing

Frontend:

• React 18 with TypeScript
• Vite for build tooling
• Tailwind CSS for styling
• React Query for state management
• React Hook Form for forms

Infrastructure:

• Docker for containerization
• Docker Compose for local development
• Render.com for easy deployment
• GitHub Actions for CI/CD

System Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   React App     │    │   Restaurant    │    │   Admin Portal  │
│   (Frontend)    │    │   Partner Portal│    │   (Management)  │
└─────────┬───────┘    └─────────┬───────┘    └─────────┬───────┘
          │                      │                      │
          └──────────────────────┼──────────────────────┘
                                 │
                    ┌────────────▼────────────┐
                    │    Express.js API       │
                    │    (Backend Server)     │
                    └────────────┬────────────┘
                                 │
                    ┌────────────▼────────────┐
                    │     PostgreSQL DB       │
                    │    (Primary Storage)    │
                    └────────────┬────────────┘
                                 │
                    ┌────────────▼────────────┐
                    │        Redis            │
                    │    (Caching/Session)    │
                    └─────────────────────────┘
                                 │
                    ┌────────────┬────────────┐
                    │            │            │
          ┌─────────▼──┐  ┌──────▼────┐  ┌───▼──────┐
          │   Stripe   │  │ Cloudinary  │  │ SendGrid │
          │  Payments  │  │  Images     │  │  Email   │
          └────────────┘  └─────────────┘  └──────────┘

📖 Documentation

• System Architecture - Detailed technical architecture
• Project Structure - Code organization and structure
• Deployment Guide - Step-by-step deployment instructions
• API Documentation - Complete API reference

🎯 Key Features (Implemented)

User Experience

• ✅ Email/Password Registration - Simple account creation
• ✅ Profile Completion - Name, age, bio, interests, goals (interests/goals optional)
• ✅ Preferences Setup - Age range, distance radius, interests
• ✅ Discover Restaurants - Browse local partner restaurants
• ✅ Proximity-Based Matching - PostGIS-powered location matching
• ✅ Real Bookings - Create bookings with voucher codes and QR codes
• ✅ Voucher System - 8-character unique codes per booking
• ✅ QR Code Generation - Scannable codes for restaurant validation
• ✅ State Persistence - Onboarding progress saved to localStorage

Restaurant Partner Experience (Data Seeded)

• ✅ Restaurant Profiles - Name, description, location, cuisine type
• ✅ Package Management - Date night packages with pricing
• ✅ Availability Slots - Time-based booking slots
• ✅ Capacity Management - Track current bookings vs capacity
• 🚧 Partner Portal - Planned for future release

Technical Features

• ✅ JWT Authentication - Secure token-based auth
• ✅ PostGIS Integration - Geo-spatial queries for proximity matching
• ✅ Joi Validation - Schema-based input validation
• ✅ Docker Deployment - Full containerization
• ✅ TypeScript - Type-safe backend and frontend
• ✅ Context-Based State - Global auth and onboarding contexts

Features In Progress

• 🚧 Email Verification - Currently bypassed (auto-verified)
• 🚧 Stripe Payments - Integration stubbed
• 🚧 Real-time Messaging - Basic messaging structure in place
• 🚧 Image Uploads - Currently base64, plan to use Cloudinary

📚 Documentation

• Functional Specification - Complete feature documentation
• API Documentation - API endpoints and usage (see functional spec)
• Database Schema - Table structures and relationships (see functional spec)
• Deployment Guide - Docker-based deployment

🔧 Development

Project Structure

LSDN/
├── backend/              # Node.js + Express API
│   ├── src/
│   │   ├── entities/     # TypeORM entities
│   │   ├── routes/       # API route handlers
│   │   ├── services/     # Business logic
│   │   ├── middleware/   # Auth, validation, etc.
│   │   └── scripts/      # Migration and seed scripts
│   └── dist/             # Compiled TypeScript
├── frontend/             # React + Vite frontend
│   ├── src/
│   │   ├── components/   # Reusable UI components
│   │   ├── contexts/     # React contexts (Auth, Onboarding)
│   │   ├── hooks/        # Custom React hooks
│   │   └── pages/        # Page components
│   └── dist/             # Production build
├── docker-compose.yml    # Docker services configuration
└── docs/                 # Additional documentation

Environment Setup

The application uses environment variables for configuration. Key variables:

Backend:

• DATABASE_URL - PostgreSQL connection string
• REDIS_URL - Redis connection string
• JWT_SECRET - JWT signing secret
• FRONTEND_URL - CORS allowed origin

Frontend:

• VITE_API_URL - Backend API URL (handled by Vite proxy)

Testing

# Backend tests (when implemented)
cd backend
npm run test

# Manual API testing
curl http://localhost:3000/api/restaurants

📊 Metrics and Monitoring

Key Performance Indicators

• Completed first dates per active user per month
• Restaurant partner NPS
• GMV and take rate
• Sign-up to package purchase conversion
• Ask to accept rate
• Show rate and no-show rate
• Slot utilization per venue

Monitoring Setup

• Application logs
• Database performance
• API response times
• Error tracking
• User analytics

🛡️ Security

Authentication

• JWT with refresh tokens
• Password hashing with bcrypt
• Email verification required

Authorization

• Role-based access control
• API rate limiting
• Input validation and sanitization

Data Protection

• HTTPS only
• Encrypted database connections
• Secure file uploads
• Regular security audits

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

1. Fork the repository
2. Clone your fork
3. Create a feature branch
4. Make your changes
5. Add tests
6. Submit a pull request

📄 License

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

🙏 Acknowledgments

• React - UI library
• Express.js - Web framework
• PostgreSQL - Database
• Stripe - Payment processing
• Cloudinary - Image processing
• Render.com - Easy deployment

📞 Support

For support and questions:

• Create an issue in this repository
• Join our community discussions
• Contact the development team

---

Local Singles Date Night - Making dating local, meaningful, and community-focused. ❤️