HealLink

GIF
HealLink Preview

Inspiration

Patients undergoing serious medical procedures often find themselves in an information vacuum filled with anxiety. While doctors provide critical medical advice, they can't always convey the day-to-day reality of the experience—the small tips for managing side effects, the emotional toll of recovery, or how to navigate life post-treatment. Friends and family offer support, but the empathy gap is real; it's hard to understand unless you've been through it yourself.

HealLink was born from this realization: the most valuable resource for a patient is often someone who has already walked the same path. We were inspired to build a platform that bridges this gap, using technology not just to connect people, but to find the right person who truly understands their journey, their concerns, and even their lifestyle.

What it does

HealLink is a private, secure web application that connects individuals seeking support for a medical procedure (mentees) with volunteers who have successfully been through a similar experience (mentors).

Here's the core user journey:

Simple Onboarding: A user signs in with just their email. If they are new, they are guided to complete a profile.
Detailed Profile Creation: Users share their procedure, current stage, hospital, and personal details like interests and a short introduction about their journey. This intro is the key to our AI matching.
AI-Powered Matching: A mentee's primary action is to "Find My Best Match." Our backend converts their introduction into a mathematical vector and uses semantic search to find a mentor with the most similar lived experience, going far beyond simple keyword matching.
Manual Search & Filtering: For users who prefer more control, a gallery of available mentors can be browsed and filtered by attributes like age, gender, hospital, and language.
Real-Time, Private Chat: Once a mentor is selected, a direct, one-on-one chat room is opened. The conversation is powered by WebSockets for instant, real-time communication.
AI Icebreakers: To help start a sometimes-difficult first conversation, the chat interface includes an AI-powered feature to generate personalized, empathetic opening questions.
Mentor Dashboard: Mentors have a simple dashboard to view all the mentees who have connected with them, allowing them to manage their conversations easily.

How we built it

We developed HealLink as a full-stack application, prioritizing a modern, responsive user experience and a powerful, AI-driven backend.

Frontend:

Framework: React with Vite for a fast and modern development environment.
Styling: Tailwind CSS for a utility-first, fully custom design system.
UI/UX: Icons from lucide-react and animations powered by framer-motion to create a fluid, intuitive, and reassuring user interface. The landing page features a subtle 3D background using @react-three/fiber.
API Communication: axios for handling RESTful API calls and the native WebSocket API for the real-time chat functionality.

Backend:

Framework: Python with FastAPI, chosen for its high performance, automatic data validation with Pydantic, and native support for WebSockets.
Database: SQLite with the SQLAlchemy ORM for rapid prototyping and simplicity.
Real-Time Layer: A WebSocket manager built in FastAPI handles all live chat connections and message routing.

Artificial Intelligence Core:

Semantic Matching Engine:
- Embeddings: We use the sentence-transformers library (all-MiniLM-L6-v2 model) to convert the text from a user's intro into a 384-dimension vector embedding. This captures the semantic meaning and "vibe" of their story.
- Vector Search: Facebook AI's faiss library is used to create a high-speed, in-memory index of all mentor embeddings. When a mentee requests a match, we perform a similarity search to find the vector (and thus, the mentor) that is mathematically closest to theirs.
Generative AI & Privacy:
- Local LLM: We integrated with a local Ollama server running Google's Gemma model.
- Functionality: This powers our generate_introduction service and the AI icebreakers. By running the LLM locally, we ensure that sensitive user conversations and profile data are never sent to a third-party API, guaranteeing user privacy.

Challenges we ran into

API Response Mismatch: A classic backend challenge arose when our get_user_by_email endpoint would return null if a user wasn't found. FastAPI's Pydantic models would fail validation on this null response, causing a generic 500 server error instead of a clean 404. We had to refactor the endpoint to explicitly check for None and raise a proper HTTPException, which was a great lesson in robust error handling.
Providing User Feedback for AI Tasks: The AI matching process isn't instantaneous. Initially, clicking the "Find Match" button left the user staring at a disabled button with no feedback. This felt broken. Our solution was to implement a full-screen, animated loading overlay (MatchLoadingAnimation.jsx) using framer-motion, which significantly improved the user experience by communicating that a sophisticated process was running.
Disappearing Mentor Info: In a late-stage refactor, we accidentally replaced the detailed mentor card component with a placeholder comment, causing the entire mentor list to render as blank cards with just a "Start Chatting" button. It was a humbling reminder to always double-check component composition after making changes.

Accomplishments that we're proud of

Privacy-First AI: Our biggest accomplishment is building a functional AI pipeline that completely respects user privacy. By using local, open-source models for both embeddings and generation, we created a powerful feature set without exposing any sensitive health data to external services.
Meaningful Semantic Search: We successfully implemented a matching system that goes beyond simple filters. It connects people based on the nuance of their stories, which we believe is the core of what makes peer support effective.
A Polished and Empathetic UI: We invested time in making the interface feel calm, professional, and trustworthy. The smooth animations, clean layout, and thoughtful features like AI icebreakers contribute to a user experience that feels supportive, not just functional.
End-to-End Real-Time System: Building a stable, full-stack application with a real-time chat system powered by WebSockets from scratch was a major technical achievement for our team.

What we learned

Vector Search is a Superpower: We learned that semantic search is an incredibly powerful tool for creating more human-centric applications. The ability to match based on meaning rather than keywords is transformative.
Local LLMs are Ready: For scoped, specific tasks, local LLMs are no longer just experimental toys. They are fast, effective, and offer a clear path to building privacy-focused AI features.
User Experience is Paramount: A sophisticated backend is only as good as the user's perception of it. Clear loading states, smooth animations, and intuitive design are not just polish; they are essential for building trust and engagement, especially in a health-focused application.

What's next for HealLink

Persistent Vector Database: To scale beyond a hackathon prototype, we will migrate the in-memory FAISS index to a persistent vector database like ChromaDB or Weaviate.
Hybrid Search: We plan to combine our semantic search with the existing hard filters, allowing users to make queries like, "Find me the best match who is also a woman and speaks Spanish."
Community and Group Spaces: Introduce moderated group chats focused on specific procedures or recovery stages to foster a broader sense of community.
Enhanced Mentor Profiles: Allow mentors to add more details, such as "areas I can help with" (e.g., "managing anxiety," "diet tips," "returning to work"), to further refine matching.
Deployment and Security: Containerize the application with Docker and deploy it on a secure cloud platform, implementing stricter security protocols and a mentor vetting process to ensure community safety.