SpotDrop: Microservices-Based AI Event Platform

An enterprise-grade, location-based event discovery and booking platform. SpotDrop utilizes a microservices architecture to identify vacant event spots and dynamically match them with users through AI-driven extraction, collaborative filtering, and schedule-aware recommendations.

System Architecture

SpotDrop is designed with a scalable, decoupled microservices topology:

• Presentation Tier: Cross-platform mobile application built with Flutter.
• Logic Tier (API Gateway): Laravel/PHP backend managing user authentication (Sanctum/Firebase), payment processing (Stripe), and core business routing.
• Data & AI Microservice: A high-performance FastAPI (Python) server dedicated to asynchronous web scraping, Natural Language Processing (NLP), and recommendation algorithms.
• Database Tier: PostgreSQL relational database for robust data persistence.

Core Engineering Highlights

1. Asynchronous AI Web Scraper

• Concurrent Crawling: Leverages Playwright and httpx to efficiently navigate and extract dynamic DOM content from platforms like SF Funcheap and Eventbrite.
• LLM Data Normalization: Integrates OpenAI's gpt-4o with strict JSON-schema enforcement to parse unstructured HTML into highly structured event entities (title, datetime, location, description).
• Idempotent Operations: Implements robust database Upserts (on_conflict_do_update in SQLAlchemy) using source URLs as unique constraints, guaranteeing data integrity and zero duplication during concurrent cron jobs.

2. Hybrid Recommendation Engine

• Item-kNN Collaborative Filtering: Computes event-to-event similarity utilizing scipy sparse matrices (CSR) and cosine similarity to generate personalized recommendations based on implicit user interactions.
• Schedule-Aware Filtering: Integrates the Google Calendar API to fetch users' busy slots, applying complex datetime logic to exclusively recommend events that perfectly fit their availability (with automated 15-minute buffer windows).

3. NLP Chatbot & Smart Notifications

• Conversational Discovery: Features an OpenAI-powered Chatbot MVP that cross-references user queries with database inventory to return context-aware JSON event payloads.
• Automated Copywriting: Uses engineered prompts to dynamically generate highly engaging, constraint-bound (<160 characters) push notifications tailored to specific user interests.

4. CI/CD & Automated Testing

• Comprehensive Test Suite: Employs pytest and pytest-asyncio for extensive unit and integration testing.
• External Dependency Mocking: Ensures deterministic testing and zero API costs by rigorously mocking OpenAI, PostgreSQL, and Google Maps interfaces using unittest.mock.
• GitHub Actions: Configured automated CI pipelines (test.yml, test_calendar_event_rec.yml) to validate code integrity on every push and pull request.

Technology Stack

• Frameworks: FastAPI, Uvicorn, SQLAlchemy (Async)
• Data & AI: OpenAI API, SciPy, NumPy, Pandas
• Scraping: Playwright, BeautifulSoup4, HTTPX, AIOHTTP
• Integrations: Google Maps Geocoding API, Google Calendar API
• Testing: Pytest, Pytest-Asyncio, Pytest-Mock
• Deployment: Railway (Nixpacks)

---

Local Development

1. Environment Setup

Requires Python 3.8+. Create and activate a virtual environment:

python3 -m venv .venv
source .venv/bin/activate

2. Install Dependencies

Install the required packages and Playwright browser binaries:

pip install -r requirements.txt
playwright install chromium

3. Configuration

Create a .env file in the root directory:

OPENAI_API_KEY=your_openai_api_key
GOOGLE_MAPS_API_KEY=your_gmaps_api_key
DATABASE_URL=postgresql+asyncpg://user:password@localhost:5432/spotdrop_db

4. Run the API Server

Launch the FastAPI microservice with hot-reload:

uvicorn backend.app.main:app --reload

Testing

Execute the automated test suite to validate data models, mocked AI extraction, and calendar logic:

# Run all tests
pytest -v

# Run specific component tests
pytest -v tests/test_calendar_event_rec.py