Match a Cause

How we built it# Match a Cause: Swiping for Social Good

The Spark

It all started with a simple observation before ScarletHacks 2025: finding volunteer opportunities we aligned with felt impossible. On the other side, we recognized that organizations often struggle to reach enthusiastic volunteers who align with their cause. We saw a disconnect a gap we could bridge. Inspired by modern discovery apps, we asked: "What if finding your next volunteer gig was as easy as swiping left?" That question became the foundation for Match a Cause.

The Learning Curve

This hackathon was a deep dive into several exciting technologies. Building the backend with FastAPI was a primary goal. We were eager to leverage its asynchronous capabilities and capitalize on automatic documentation generation. Working with MongoDB as our database provided valuable experience in flexible data modeling. Implementing user authentication securely was another key learning area, ensuring that user data and interactions were protected. The most exciting part was exploring vector embeddings and similarity search because these techniques were learned in the classroom and appl– figuring out how to numerically represent events and user interests to enable intelligent matching was both challenging and rewarding.

Building the Engine: The Process

We adopted a modular approach from the start:

Foundation: We set up the basic FastAPI project structure, configuring database connections (config/db.py) and defining core data models for users and events (models/).
Core Logic: The heart of the application lies in the services/swiping.py module. Here, we devised the algorithm to process a user's swipe (like or dislike), record their preference, and intelligently select the next most relevant event based on calculated similarity scores.
API Endpoints: We exposed the functionality through RESTful API routes, using Pydantic models for data validation and serialization.
Authentication: We integrated authentication middleware (middleware/auth.py) to protect the swipe endpoint and ensure actions were tied to specific users.
Iteration: Throughout the process, we constantly tested endpoints using tools like Swagger UI (thanks to FastAPI!), debugged issues, and refined the data flow between the API layer, service logic, and database. We worked from the beginning of the user journey to the end.

Navigating the Challenges

No hackathon project is without its hurdles:

The Clock: The 24/36-hour time crunch was intense. Prioritizing features and focusing on a minimum viable product (MVP) was crucial.
Vector Similarity Nuances: Implementing the vector comparison effectively was tricky. Choosing the right embedding strategy and optimizing the similarity calculation required research and experimentation under pressure. We might have started with a simpler similarity metric before diving into full vector search.
Async Adventures: Debugging asynchronous code presented its own unique challenges, requiring careful handling of await calls and understanding event loops.
Data Seeding: Getting realistic initial data for events to test the recommendation logic required some creative scripting or manual effort.
API Design Hiccups: Ensuring the request (SwipeAction) and response (EventResponse) models accurately reflected the data needed and returned by the handle_swipe_action endpoint involved some trial and error.
Resource Scarcity The Groq API offers powerful utilities as a free service, but like most free tiers, it comes with certain constraints — most notably a limited token allowance. During our web crawling and scraping processes, these limitations posed challenges, especially when handling larger or more complex pages. As a result, we had to adjust our approach and scale down our original goals to operate within these restrictions.
Web Crawling & Scraping We faced several challenges while attempting to scrape data from the web, particularly when dealing with embedded links or content hidden behind script-based functions. These obstacles made it difficult to extract complete datasets. To address the gaps, we initially used AI-generated content to fill in missing information.

The Outcome and What's Next

We managed to build a functional backend API that simulates the core swipe-and-match experience for volunteer events. Users can log in, swipe on events, and receive suggestions for the next potential opportunity based on their interactions.

While the frontend wasn't built during the hackathon, the robust API provides a solid foundation. Future steps could include developing a sleek web or mobile interface, refining the event recommendation algorithm with more sophisticated ML models, allowing organizations to post events directly, and building out richer user profiles. ScarletConnect started as a hackathon idea, but its potential to genuinely connect volunteers with causes they care about feels significant.

Currently, our data scraper operates independently from the main application. The scraped event data is stored in CSV files, which are then manually processed and integrated into the app. While this approach has worked during development, it introduces delays and requires additional effort for updates.

Looking ahead, we aim to fully integrate the scraper with our backend, enabling automated data collection and daily updates directly to the server. This will streamline the workflow, reduce manual intervention, and ensure users always have access to the most up-to-date information.

While the app is currently in development, we plan to deploy it in the near future to make it publicly accessible and fully functional.

Accomplishments that we're proud of

We are proud of our first full-stack mobile application. This is our first application where we access and update a database. Beyond the technical side, we are proud of each other because of how hard we have worked. We have learned so much and have refined our problem-solving skills..