Mentora

Mentora is an AI-powered mental health companion developed as a mobile-first application to daily mood check-ins, free-text journaling, and supportive with designed as a supportive digital companion

Comment

Mentora submission · MD

Mentora — AI Mental Health Companion

Inspiration

Students and young adults live under constant academic, social, and financial pressure, and stress, anxiety, and mood instability have become part of their daily routine. Traditional therapy is still the gold standard, but cost, stigma, waiting lists, and scheduling make it hard to reach. That leaves a gap between how often people need emotional support and how often they can actually talk to a professional.

The digital alternatives didn't close that gap either. We looked at Replika, Daylio, Wysa, Sanvello, and Woebot and found the same recurring limits: emotional state compressed into a single number or emoji, free-text that is never really understood, scripted conversations that feel repetitive, coping content that is generic rather than matched to the person, and almost no explicit crisis detection anywhere. Users log data, but that data rarely turns into the right suggestion at the right moment, and nothing warns them when a long run of low-mood days is building up.

We also noticed something closer to home: most of these tools completely miss how Arabic-speaking youth actually write. Franco-Arabic and Arabizi text like "msh 3aref anam" gets ignored by systems that only recognize formal English.

So we built Mentora — a private, always-available space where someone can log their mood, journal, and talk to a supportive companion, designed to complement professional care rather than replace it.

What it does

Mentora is a mobile-first AI mental health companion built around eight structured psychological parameters: anxiety, depression, stress and pressure, sleep and energy, social connection, cognitive distortions, safety, and engagement. Every journal entry, chat message, and mood check-in updates all eight scores, so the app holds a continuously evolving, multi-dimensional picture of the user instead of a single mood value.

  • AI chat companion — an open, non-scripted conversation that reads the user's current parameter state and tailors every reply to it. It offers CBT-inspired prompts, enforces safe-messaging boundaries, avoids diagnosis or treatment claims, and can route the user to a specific exercise instead of generic advice. Quick-start buttons like "I'm feeling anxious" or "Can't sleep" lower the effort of opening up.
  • Mood logging and parameters engine — daily check-ins with an emoji slider and an optional short text note, with the text sent for full parameter scoring.
  • Journaling — private free-text entries with optional per-entry encryption and a Locked filter. Analyzed entries return emotion tags that feed back into the parameter engine.
  • Wellness exercises library — breathing exercises with animated guidance, CBT thought records, grounding, mindfulness, and sleep hygiene routines, recommended by current severity: one exercise for mild scores, two for moderate, three for severe, so users who are already overwhelmed don't get buried in suggestions.
  • Insights dashboard — four tabs covering mood averages, streaks and best days, monthly and weekly trends, activities correlated with good days, recurring emotional triggers with coping strategies, and wellness goals with progress bars.
  • Crisis awareness — every message and entry is classified as normal, elevated, or crisis. Any non-zero safety score can never return normal, crisis language is caught even when wrapped in jokes, "lol," or emojis, and a crisis classification triggers a high-priority notification steering the user toward safety resources and human support.
  • Long-term memory — when a conversation ends, a memory profile is extracted covering personal facts, recurring patterns, which coping strategies have worked, life events, progress, and safety history, then injected into every future chat so the companion doesn't reset each session.
  • Franco-Arabic and gender-aware Arabic — mixed Arabic-Latin script is translated internally before scoring, and Arabic replies use the correct grammatical gender based on the user's profile.
  • Adaptive notifications — reminders for check-ins, journaling, and exercises that adapt to engagement patterns and respect quiet hours. ## How we built it

Mentora uses a modular three-tier architecture so each layer can be developed, updated, and scaled independently.

Mobile client — React Native (Expo managed workflow), Android. Calm, minimal UI so someone in a difficult moment can finish a key action in a few taps. Redux Toolkit handles global state with slices for auth, chat, mood, and notifications; AsyncStorage persists the JWT between launches; Axios interceptors attach the bearer token and handle 401s with a refresh flow. Breathing animations are built with the React Native Animated API.

Backend — ASP.NET Core with SQL Server. Clean architecture with controllers, services, and repositories separated. It exposes REST APIs returning a standardized JSON envelope (success flag, data payload, message), which made client-side error handling predictable. It also acts as the orchestrating gateway to the AI microservice over HTTPS via HttpClient, persisting returned scores and driving exercise selection, trend calculation, adaptive notification scheduling, and streak tracking. SignalR supports real-time chat updates.

AI microservice — Python Flask + GPT-4o-mini via the OpenAI API. The interesting design decision here was splitting clinical knowledge from application code. A ParameterLoader reads eight Excel files at startup into pandas DataFrames — one per parameter — where Sheet1 is a clause library of symptom descriptions each carrying a 0–3 severity weight, and Sheet2 maps score brackets to exercise IDs. A shared run_scoring() function serializes that clause library into the prompt, has the model match clause IDs against the user's text, sums the intensities per parameter, and returns updated scores in forced JSON mode. Exercise selection through map_scores_to_exercises() is fully deterministic and involves no model call at all. Three endpoints serve the system: /analyze for journals, /chat for conversation, and /summarize for memory.

Process and deployment. Bi-weekly Agile sprints with stand-ups, reviews, and retrospectives; GitFlow branching in a single GitHub repo with folders for mobile, backend, AI service, and docs; PR-based peer review; CI workflows triggered on merges to main. The Flask service runs on PythonAnywhere — no GPU needed since inference is delegated to OpenAI — with the Excel knowledge base in persistent storage, a /health endpoint, and the API key in environment variables. The backend and SQL Server sit in a .NET-optimized cloud environment with all secrets held as environment variables. The Android app ships as an App Bundle to Google Play, with Expo OTA updates for JavaScript-layer changes.

Challenges we ran into

Making an LLM produce numbers we could trust. Free-form model output isn't a score. We had to force pure JSON through OpenAI's response_format JSON mode and then add a post-processing safety net in run_scoring() that clamps score floors at zero and validates the risk_level enum before anything reaches the backend. Getting the model to match specific clause IDs rather than improvise severity took real prompt iteration.

Crisis language that hides. People rarely announce distress plainly. They wrap it in "lol," a joke, an emoji, or "just kidding." We wrote explicit prompt rules requiring crisis language to be caught through that framing, made any non-zero safety score incapable of returning normal, and added a programmatic fallback that enforces the classification from the numeric safety score regardless of what the model said. We tested this specifically with passive death wishes in joking framing.

Franco-Arabic. A model tuned on formal text simply misses "msh 3aref anam mn el tfker." The fix was an explicit preprocessing instruction to internally translate Franco-Arabic and Arabizi to English before any clause matching — then verifying it worked by submitting matched English/Franco-Arabic pairs and checking the parameter deltas came out equivalent.

Recovery, not just deterioration. An engine that only ever adds distress would show users a score that never improves. We added positive recovery clause items with negative deltas for the distress parameters and positive deltas for sleep, social, and engagement — then had to tune the prompt to be conservative, matching only clear statements like "I feel much better" and not vague ones like "okay" or "fine."

Latency across three hops. Every chat message travels client → backend → microservice → OpenAI and back, and it runs scoring and generation. Keeping that under five seconds while carrying full context — parameter scores, last five journal summaries, exercise list, long-term memory, and twenty turns of history — required careful management of what actually goes into each prompt.

Balancing personalization against overwhelm. More recommendations felt like more value until we thought about who receives them. Capping severe cases at three exercises was a deliberate choice against the instinct to give more.

Safety boundaries in an open conversation. Non-scripted chat is what makes Mentora feel human, and it's also what makes it risky. The companion had to stay empathetic while never diagnosing, never promising treatment outcomes, and reliably escalating — a constraint that shaped both the system prompt and the wording refinements that came out of user testing.

Orchestrating three stacks. C#, Python, and JavaScript, three deployment targets, and one contract between them. The standardized JSON envelope and stateless JWTs did a lot of work here.

Accomplishments that we're proud of

  • An emotional model with actual structure. Eight calibrated parameters derived from validated clinical screening frameworks and CBT literature — not a five-point emoji scale.
  • A knowledge base that clinicians could edit without touching code. Because the clause libraries and score-to-exercise mappings live in Excel, refining clinical content means editing a spreadsheet, not redeploying a service. For a mental health platform, that maintainability matters more than it sounds.
  • Crisis detection that survives joking framing, backed by a deterministic safety net rather than trusting the model alone.
  • Genuine support for how Arab youth actually write — Franco-Arabic scoring that matches English equivalents, plus gender-correct Arabic grammar. Almost nothing else in this space does either.
  • Deterministic exercise recommendation. Keeping selection out of the model made it reproducible, testable, and explainable.
  • A companion with continuity. Memory summarization means the AI remembers what has worked for you, which is the difference between a chatbot and a companion.

  • We shipped the whole stack. Mobile app, backend, AI service, database, and deployment pipeline — validated with unit tests (xUnit), integration tests across the full pipeline, targeted AI microservice tests, and user acceptance testing with university students whose feedback reshaped response wording, notification timing, and onboarding.

    What we learned

  • Hybrid beats pure LLM. The parts that needed to be reliable — exercise selection, risk floors, score clamping — we made deterministic. The parts that needed to be flexible — language understanding, conversation — we gave to the model. Mixing them was the single most useful architectural lesson of the project.

  • Never trust model output without a safety net. Especially where safety is involved, "the prompt says it must" is not a guarantee. Enforce it in code too.

  • Localization is deeper than translation. Franco-Arabic support and Arabic grammatical gender aren't polish. If your users write in Arabizi and your model ignores it, you're not serving them at all.

  • Separating clinical knowledge from code changes who can maintain the product. A mental health app whose content only engineers can update is an app that stops improving.

  • In wellness design, restraint is a feature. Capping recommendations, keeping the home screen uncluttered, using quick-reply buttons — the design decisions that helped most were the ones that reduced what we asked of the user.

  • Real users find what tests miss. UAT with students changed our response wording, notification timing, and onboarding flow in ways no unit test would have surfaced.

  • Being clear about what you are not is part of being trustworthy. Stating plainly that Mentora is not a replacement for professional care shaped the product for the better.

    What's next for Mentora

  • Voice-based interaction — real-time speech recognition and text-to-speech, so the companion can be used entirely by voice. This matters most in moments of high distress, when typing is exactly what someone can't manage.

  • Therapist connectivity — an optional professional tier with appointment booking, secure messaging, and therapist access to AI-generated mood summaries and parameter trends, creating a real continuum from self-guided support to professional care.

  • Offline mode — on-device inference with a lightweight quantized model, so chat, breathing exercises, and mood logging keep working without connectivity. Network problems shouldn't be a barrier during a crisis.

  • Wearable integration — pulling heart rate variability, sleep duration and quality, and activity levels from smartwatches and fitness trackers, and correlating those physiological signals with self-reported mood for more accurate, proactive assessment.

  • Smart home via IoT — our longer-term vision is Mentora as the intelligence layer of a mental health-aware living environment. Ambient light sensors, sound monitors, motion detectors, and sleep trackers would supply passive behavioral signals — extended inactivity, irregular sleep cycles, reduced lighting use, routine deviations — that combine with app data to infer emotional state without manual input. On detecting low mood or elevated stress, the home could respond by shifting lighting to warmer tones, playing guided breathing through a smart speaker, or gently prompting a journal entry. Technically this means an MQTT ingestion layer and an edge node for privacy-preserving pre-processing, plus granular consent controls — monitoring inside someone's home demands the highest standard of transparency and data minimization.

  • Gamification — mood streaks, journaling badges, exercise milestones, and wellness challenges to reinforce the habit formation that makes the whole thing work.

  • Ongoing clinical validation as the parameter framework and exercise library expand.

Share this project:

Updates

Submission history