| 🧾 License |
🛠️ Frontend CI |
📱 Expo CI |
🌟 Stars |
👀 Views |
|
|
%26logo%3Dexpo%26color%3Dblue)
|
|
|
| 🍴 Forks |
🐛 Issues |
🔄 Open PRs |
✅ Closed PRs |
|
|
|
|
| 🤖 Android Build CI |
🍎 iOS Build CI |
⏱️ Last Commit |
📦 Repo Size |
|
|
|
|
APP and WEB UPDATE:
- GSSOC CONTRIBUTOR’S TASK LIVE with new authentication system (UPCOMING, NEXT WEEK)
- New Article Publish
UltimateHealth has now moved to a new domain! 🚀
Some broken links may still exist on the server due to references to our old URL. We’re already working on it, and everything will be resolved in the next update.
📛 Repository Badges Explained
The badges displayed at the top of this README provide a quick overview of the repository’s health, activity, and development status.
| Badge |
Explanation |
| 🛠️ Frontend CI |
Shows whether the frontend code passes automated build and validation checks. |
| 📱 Expo CI |
Indicates the status of Expo EAS build workflows for the mobile application. |
| 🤖 Android Build CI |
Confirms whether the Android build validation workflow completed successfully. |
| 🍎 iOS Build CI |
Displays the status of automated iOS build validation. |
| 🌟 Stars |
Shows how many GitHub users have starred the repository. |
| 🍴 Forks |
Indicates how many people have forked the repository to contribute or experiment. |
| 🐛 Issues |
Displays the current number of open issues awaiting resolution. |
| 🔄 Open PRs |
Shows the number of pull requests that are currently under review. |
| 🧾 License |
Identifies the open-source license under which the project is distributed. |
| 👀 Views |
Shows the approximate number of repository profile views. |
| ⏱️ Last Commit |
Indicates when the latest commit was pushed to the repository. |
| 📦 Repo Size |
Displays the current size of the repository. |
Maintainer Notice
| What you can expect |
Timeline |
| Issue auto-triaged and labelled |
Within minutes of opening |
| PR automated code review posted |
Within minutes of opening |
| Self-service issue assignment |
Instant — just comment to claim |
| Final human review by @SB2318 |
24-72 hours depending on queue depth |
Table of Contents
📖 Overview
Our AI bot suite handles the initial pipeline automatically. See Automation & Bot System for a full breakdown.
Documentation update for issue #2224.
About the Project
UltimateHealth (also known as HealthGuide) is a fully open-source platform that combines a React Native mobile app, a Next.js web frontend, a Node.js REST API, and a Python content intelligence service — all working together to deliver trusted health content worldwide.
Live Platform: ultimatehealth.blog | Android App: Play Store
🏗️ Architecture Overview
UltimateHealth is organized into multiple components, each responsible for a specific part of the platform. These components communicate through the backend API to provide a consistent experience across mobile and web applications.
UltimateHealth
│
┌──────────────────┼──────────────────┐
│ │ │
▼ ▼ ▼
React Native App Next.js Web App Documentation
│ │
└──────────┬───────┘
▼
Node.js REST API
│
┌─────────┴─────────┐
▼ ▼
MongoDB Python Content
Intelligence Service
| Component |
Responsibility |
| React Native (Expo) Mobile App |
Mobile application for Android and iOS users. |
| Next.js Web Frontend |
Browser-based interface for accessing UltimateHealth. |
| Node.js REST API |
Handles authentication, business logic, and communication with backend services. |
| Python Content Intelligence Service |
Performs plagiarism detection, grammar analysis, and originality scoring. |
Where to Contribute
- Mobile features →
frontend/
- Backend functionality → Node.js backend repository
- Content intelligence → Python content service repository
- Documentation →
README.md and docs/
Features
| Feature |
Description |
| Multilingual Articles |
Write and read health content in any language |
| Collaborative Reviews |
Community editing, feedback and approval workflow |
| Health Podcasts |
Publish and stream verified health podcasts |
| AI Health Chat |
AI-powered assistant for health-related queries |
| Contribution Analytics |
Track your contribution impact |
| Content Integrity |
Plagiarism detection, grammar checks and originality scoring |
| Community Safety |
Flagging system and RBAC for reviewers and admins |
| Guest Mode |
Read articles and listen to podcasts without signing in |
| Content Preferences |
Save preferences for a personalized experience |
| Translation Support |
Extend any article in your preferred language |
Admin Features: Interactive review dashboard, moderation tools and analytics.
🧩 Feature-to-Technology Mapping
The following table explains which technologies power different features of UltimateHealth. This helps contributors identify the correct project area when contributing to a specific feature.
| Feature |
Primary Technology |
| AI Health Chat |
Node.js + Python Content Intelligence API |
| Podcasts |
React Native + Expo |
| Multilingual Articles |
React Native + Node.js REST API + Python Content Intelligence API |
| Content Integrity |
Python Content Intelligence API |
| Authentication |
Node.js REST API + MongoDB |
| Health Tracking |
React Native + Node.js REST API + MongoDB |
| User Profile Management |
Node.js + MongoDB |
| Mobile Application |
React Native + Expo |
| Web Platform |
Next.js |
Tech Stack
Mobile App (React Native + Expo)
| Layer |
Technology |
| Framework |
React Native + Expo |
| Language |
TypeScript / JavaScript |
| State Management |
Context API / Redux |
| Navigation |
React Navigation |
| Build System |
EAS Build (Expo Application Services) |
| CI/CD |
GitHub Actions |
Backend API (Node.js)
Content Intelligence API (Python)
Web Frontend (Next.js)
UltimateHealth is designed to support both development and end-user deployment across multiple platforms. The following table summarizes the officially supported platforms and any platform-specific requirements.
| Platform |
Support |
Notes |
| Android |
✅ |
React Native (Expo) mobile application |
| iOS |
✅ |
Supported through Expo; macOS required for native builds |
| Web |
✅ |
Next.js web frontend |
| Windows |
✅ |
Supported for local development |
| Linux |
✅ |
Supported for local development |
| macOS |
✅ |
Supported for development and required for iOS builds |
Note: Android, iOS, and Web are officially supported deployment platforms. Windows, Linux, and macOS are supported development environments.
Latest Releases
Mobile App — v2.2.0
Platform: React Native (Expo)
- Security improvements
- Podcast enhancements
- Accessibility updates
- Performance optimizations
|
Web App — v2.0.0
Platform: Next.js
- Modern web experience
- Improved routing
- Enhanced UI/UX
- Better performance
|
🗺️ Project Roadmap & Release Pipeline
Following our October 2026 Core Release (v3.2.0), the next product releases follow a milestone-driven pipeline to systematically activate, polish, and deploy all currently hidden and newly integrated modules.
📅 Release Pipeline & Deadlines
| Phase & Milestone |
Target Version |
Deadline |
Key Features & Deliverables |
Status |
| October Foundation Release |
v3.2.0 |
Oct 31, 2026 |
• System-wide Dark Mode sync with Tamagui bundle deduplication
• 2-Step Frictionless Onboarding (Role picker & 1-click Google auth)
• Protected Guest Browsing Mode with contextual placeholders & HomeScreen “Exit Guest” shortcut
• Filter & Search BottomSheet Modal dark theme alignment
• 13 Indian Regional Languages Localization Framework (src/localization)
• Dynamic Settings App Language Selector with live reactive re-rendering
• Article DetailsScreen dark WebView content rendering
• Podcast listing screen dark theme sync & skeleton loading
• Resilient offline reading & wellness no-internet fallbacks |
✅ Shipped |
| Phase 1: Health Intelligence Sprint |
v3.3.0 |
Apr 30, 2027 |
• Medical Glossary (MedicalGlossaryScreen): Unhide and link in Settings & Global Search with A-Z category chips & medical pronunciation
• Health Term Comparison (HealthTermComparisonScreen): Interactive side-by-side comparison tables
• AI Suggestion Acceptance (RenderSuggestion): Integrated diff preview and accept/reject actions for AI article improvements in Editor
• Social Circle (SocialScreen): Real-time socket-based follower & following lists accessible from profiles |
⚡ In Active Development |
| Phase 2: Community & Local Health |
v3.4.0 |
Aug 31, 2027 |
• Nearby Health Events (NearbyHealthEventsScreen, EventDetailsScreen): Live backend API integration for blood donation drives, health camps, and vaccine drives with GPS distance sorting
• Verified Medical Contributor Directory: Dedicated doctor & medical contributor showcase with specialty filters
• Multi-Language Translation Module: Real-time article and interface localization across regional languages |
📋 Scheduled |
| Phase 3: Healthcare Academy Major |
v3.5.0 |
Dec 31, 2027 |
• Healthcare Learning Academy (AcademyStackNavigation): Full activation of all 9 academy modules
• Interactive Courses & Lessons (CourseListingScreen, CourseDetailScreen, LessonReaderScreen)
• Patient Journeys & Clinical Workflows (PatientJourneyScreen, WorkflowScreen)
• Hospital Map & Navigator (HospitalMapScreen)
• Medical Quizzes & Certification (QuizScreen, AcademyProfileScreen) |
📋 Planned |
📋 Feature Implementation & Visibility Status
| Feature / Screen |
Primary Technology / Route |
Implementation State |
Current UI Visibility |
Target Activation |
| Dark Theme Sync |
React Native useColorScheme + Tamagui |
Completed |
Active App-Wide |
✅ Released (v3.2.0) |
| Guest Mode & Onboarding |
Redux isGuest + OnboardingModal |
Completed |
Active App-Wide |
✅ Released (v3.2.0) |
| 13-Language App Localization |
src/localization/ (i18n.ts + useTranslation) |
Completed |
Active in Settings & Home |
✅ Released (v3.2.0) |
| Filter & Search Modal Dark Sync |
FilterModal.tsx + CategoriesFlatlistModal.tsx |
Completed |
Active in Article Search |
✅ Released (v3.2.0) |
| Medical Glossary & Term Dictionary |
MedicalGlossaryScreen.tsx |
Completed |
🔒 Hidden (Unlinked) |
v3.3.0 (Apr 30, 2027) |
| Health Term Comparison Tool |
HealthTermComparisonScreen.tsx |
Completed |
🔒 Hidden (Unlinked) |
v3.3.0 (Apr 30, 2027) |
| AI Editor Suggestion Diff |
RenderSuggestion.tsx |
Completed |
🔒 Hidden (Trigger Unlinked) |
v3.3.0 (Apr 30, 2027) |
| Social Follower Circle |
SocialScreen.tsx |
Completed |
🔒 Hidden (Nav Unlinked) |
v3.3.0 (Apr 30, 2027) |
| Nearby Health Events & Camps |
NearbyHealthEventsScreen.tsx |
UI Mockup |
⚠️ Settings (“Coming Soon”) |
v3.4.0 (Aug 31, 2027) |
| Healthcare Learning Academy |
9 screens in src/screens/academy/ |
Completed |
🔒 Hidden (Stack Unmounted) |
v3.5.0 (Dec 31, 2027) |
Getting Started
Prerequisites
The following tools are required for setting up the development environment:
Version Compatibility Matrix
The following versions are recommended for a smooth development setup. Using these versions helps avoid compatibility issues during installation and development.
| Tool |
Recommended Version |
Notes |
| Node.js |
>=18.x |
Required runtime |
| Yarn |
>=1.22.x |
Recommended package manager |
| Expo SDK |
Current supported version |
Match the SDK used by the project |
| Expo CLI |
Latest |
Install globally for Expo commands |
| Android Studio |
Latest |
Includes Android SDK and Emulator |
| Xcode |
Latest (macOS only) |
Required for iOS builds on macOS |
Installation
1. Fork and Clone
git clone https://github.com/<your-username>/UltimateHealth.git
cd UltimateHealth
2. Configure Environment
cp .env.example .env
# Edit .env with your API URLs and keys
Never commit your .env file. It is already in .gitignore.
3. Install Dependencies
cd frontend
yarn install
4. Install Expo and EAS CLI
npm install -g expo-cli eas-cli
5. Android SDK Setup (Linux/macOS)
chmod +x setup-android.sh
./setup-android.sh
Skip this step if you only plan to preview the app via Expo Go (step 6 below) rather than building natively.
6. Run the App
# Android
npx expo prebuild --clean
npx expo run:android
# iOS (macOS only)
npx expo prebuild --clean
npx expo run:ios
# Quick preview via Expo Go
npx expo start
Common Commands
The following commands are commonly used during local development.
| Command |
Description |
yarn install |
Install all project dependencies. |
npx expo start |
Start the Expo development server. |
npx expo run:android |
Build and run the app on an Android device or emulator. |
npx expo run:ios |
Build and run the app on an iOS simulator (macOS only). |
npx expo prebuild --clean |
Regenerate native Android and iOS projects from the Expo configuration. |
Glossary
- Expo – A framework and toolset for building React Native applications.
- EAS – Expo Application Services used to build and deploy Expo apps.
- CI/CD – Automated workflows that test and deploy code changes.
- JWT – JSON Web Token used for secure user authentication.
- RBAC – Role-Based Access Control manages user permissions based on roles.
- Swagger – A tool for documenting and testing REST APIs.
- MongoDB – A NoSQL database used to store application data.
- REST API – An interface that allows applications to communicate over HTTP.
- API – Application Programming Interface that enables communication between software systems.
- README – The main documentation file that explains the project setup and usage.
Project Structure
UltimateHealth/
├── frontend/ # React Native (Expo) mobile app
│ ├── src/
│ │ ├── components/ # Reusable UI components
│ │ ├── screens/ # App screens and pages
│ │ ├── navigation/ # Navigation configuration
│ │ ├── services/ # API service calls
│ │ ├── context/ # React Context providers
│ │ └── utils/ # Helper utilities
│ ├── app.json
│ └── package.json
├── ieee-submodules/ # IEEE IGDTUW open source contributions
├── .github/
│ ├── workflows/ # GitHub Actions CI/CD and Bot workflows
│ └── scripts/ # AI bot Python scripts
├── docs/ # Documentation files
├── .env.example
├── setup-android.sh
├── BACKEND_SETUP.md
├── CONTRIBUTING.md
├── CODE_OF_CONDUCT.md
├── Learn.md
└── README.md
The backend (Node.js + MongoDB) and web frontend (React) live in separate repositories. See Services and Dependencies.
Development Workflow
1. Fork the repository
2. Create a feature branch from main
git checkout -b feat/your-feature-name
3. Make your changes and commit
git add .
git commit -m "feat: describe your change"
4. Push your branch
git push origin feat/your-feature-name
5. Open a Pull Request targeting the main branch
6. Wait for CI + AI bot review, then request human review
Branch Naming
| Prefix |
Use for |
feat/ |
New features |
fix/ |
Bug fixes |
docs/ |
Documentation updates |
refactor/ |
Code refactoring |
test/ |
Tests |
chore/ |
Build scripts, CI, tooling |
Commit Messages
Follow Conventional Commits:
feat: add multilingual article support
fix: resolve crash on podcast playback
docs: update README environment setup
chore: update GitHub Actions workflow
Build & Deployment
Local Development
cd frontend
npx expo start --dev-client
Production Build via EAS
# Android APK/AAB
eas build --platform android --profile production
# iOS IPA (macOS + Apple Developer account required)
eas build --platform ios --profile production
Builds are also triggered automatically via GitHub Actions on pushes to main.
🧪 Testing
UltimateHealth includes a comprehensive test suite covering components, hooks, utilities, and Redux slices. The tests use Jest and React Native Testing Library (RNTL).
- Available Tests: 456 tests across 130 test suites.
- Coverage & Purpose: The test suite validates core UI components (screens, cards, buttons), custom hooks (API data fetching and mutations), Redux state management (User, Network, Data slices), and helper services (date utilities, platform notifications).
- Current Status:
(130/130 suites passing)
Running Tests Locally
cd frontend
yarn test
For more details on our testing standards, refer to TEST_GUIDELINES.md.
Services & API Dependencies
Submodule Repositories
For local development, update your .env to point to either the live APIs or locally running services.
🛠️ Troubleshooting
1. Android SDK Path Not Found
Error:
ANDROID_HOME is not set or SDK not found
Fix:
# Add to ~/.bashrc or ~/.zshrc
export ANDROID_HOME=$HOME/Android/Sdk
export PATH=$PATH:$ANDROID_HOME/emulator
export PATH=$PATH:$ANDROID_HOME/tools
export PATH=$PATH:$ANDROID_HOME/platform-tools
# Then reload
source ~/.bashrc
2. Expo Go Version Mismatch
Error:
SDK version mismatch — project uses SDK X but Expo Go supports SDK Y
Fix:
- Update Expo Go on your device to the latest version from Play Store / App Store
- Or use a Development Build instead of Expo Go:
npx expo start --dev-client
3. Metro Bundler Port Conflict
Error:
Port 8081 is already in use
Fix:
# Kill the process using port 8081
npx kill-port 8081
# Or start Metro on a different port
npx expo start --port 8082
4. iOS Build Failing Without Apple Developer Account
Error:
No signing certificate or provisioning profile found
Fix:
- iOS builds require a paid Apple Developer Account ($99/year)
- For local testing without an account, use the iOS Simulator on macOS:
npx expo start --simulator
For production iOS builds, configure credentials via EAS:
eas credentials
5. yarn install Failing / Dependency Conflicts
Error:
Cannot find module or peer dependency conflict
Fix:
# Clear cache and reinstall
rm -rf node_modules
yarn cache clean
yarn install
6. npx expo prebuild Errors
Error:
Native project already exists
Fix:
# Use --clean flag to reset native project
npx expo prebuild --clean
7. Node.js Version Incompatibility
Error:
Unsupported engine — expected Node >= 18.x
Fix:
Use nvm (Node Version Manager) to switch versions easily:
# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
# Install and use correct Node version
nvm install 18
nvm use 18
Or use fnm (Fast Node Manager) as a lighter alternative:
fnm use 18
Automation & Bot System
This repository uses a custom suite of AI-powered GitHub Actions bots to automate the contribution pipeline. Every issue and PR goes through this automated system before any human review.
Bot 1 — AI Issue Triage
Workflow: ai_issue_triage.yml | Script: .github/scripts/ai_issue_triage.py
| Property |
Detail |
| Trigger |
New issue opened or manual dispatch |
| AI Model |
Gemini 2.5 Flash |
| What it does |
Reads title and body, cross-references recent issues and commit history, then classifies and labels the issue |
Labels applied automatically:
| Label |
Meaning |
type:bug |
A confirmed bug report |
type:feature |
A new feature request |
type:documentation |
Documentation-only change |
type:question |
A question or help request |
frontend-web |
Affects the Next.js web app |
frontend-mobile |
Affects the React Native mobile app |
backend |
Affects the Node.js API |
level:beginner |
Good first issue — minimal complexity |
level:intermediate |
Requires codebase familiarity |
level:advanced |
Requires architectural knowledge |
level:critical |
Urgent — affects production |
Duplicate detection: Checks recent issues before labelling to avoid duplicates.
Escalation: level:critical and medical/doctor-related issues are flagged to the maintainer.
Bot 2 — AI Auto-Assignment
Workflow: ai_issue_triage.yml (same file, issue_comment trigger)
| Property |
Detail |
| Trigger |
Any new comment on an issue |
| AI Model |
None — pure GitHub API logic |
| What it does |
Detects assignment requests and assigns eligible contributors instantly |
How to get assigned: Comment something like “Can I work on this?”, “I would like to take this”, or “Assign me please”.
Eligibility rules:
- Issue must be open and already labelled (triaged)
- You must have zero other active assigned issues in this repo
- Bot comments are ignored automatically
- Already-assigned issues will not be reassigned
Since no AI model is involved, assignment is nearly instant.
Bot 3 — AI PR Reviewer (Instant)
Workflow: ai_reviewer.yml | Script: .github/scripts/ai_reviewer.py
| Property |
Detail |
| Trigger |
New pull request opened or manual dispatch |
| AI Model |
Gemini 2.5 Flash |
| What it does |
Fetches PR diff, filters noise (lockfiles, build artifacts), posts a structured review |
Review structure:
Critical -- Must fix before merge
Important -- Should fix
Suggestions -- Optional improvements
Applies gssoc label to mark bot-reviewed PRs.
Bot 4 — Automated PR Reviewer (Smart Re-review)
Workflow: automated_reviewer.yml | Script: .github/scripts/automated_reviewer.py
| Property |
Detail |
| Trigger |
New pull request opened or manual dispatch |
| AI Model |
Gemini 2.5 Flash |
| Cooldown |
168 hours (7 days) after last review |
| What it does |
Label-aware, context-aware reviewer that tracks previous review history |
Smart skip conditions:
- PR contains only lockfiles, build artifacts, or auto-generated files
- PR was already reviewed within the cooldown window
- PR has no reviewable diff
Re-review trigger: After 168h + new commits pushed, the bot posts a follow-up review checking if previous feedback was addressed.
All Other Workflows
| Workflow |
Trigger |
Purpose |
greetings_issue.yml |
New issue or PR |
Friendly welcome message |
pr_greet.yml |
New PR |
Greets first-time contributors |
close-old-issue.yml |
Scheduled |
Closes stale issues |
close-old-pr.yml |
Scheduled |
Closes stale PRs |
auto-comment-pr-merge.yml |
PR merged |
Thank-you comment on merge |
close-on-merge.yml |
PR merged |
Auto-closes linked issue |
autocomment-iss-close.yml |
Issue closed |
Closing message on issue |
update-contributors.yml |
Push to main |
Keeps contributors table updated |
pr-governance.yml |
PR events |
Enforces PR standards |
pr-title-checker.yml |
PR opened/edited |
Validates Conventional Commit title |
mentor.yml |
Issue/PR events |
Mentor guidance for new contributors |
frontend-ci.yml |
Push / PR to main |
Lint and type-check |
eas-build.yml |
Push to main |
Expo EAS build (Android + iOS) |
android-build-validation.yml |
Push / PR |
Android build validation |
ios-build-validation.yml |
Push / PR |
iOS build validation |
knip-check.yml |
Push / PR |
Dead-code analysis (Knip) |
Frontend dead-code checks use Knip. See Knip Guide and Knip Contributor Guide.
🤝 Contribution Workflow
New to open source? Follow this simple workflow to contribute to UltimateHealth.
flowchart LR
A[Find an Issue] --> B[Request Assignment]
B --> C[Fork Repository]
C --> D[Create Feature Branch]
D --> E[Make Changes]
E --> F[Submit Pull Request]
F --> G[CI Checks]
G --> H[Maintainer Review]
H --> I[Merge]
This workflow summarizes the standard contribution process for all new contributors. Following these steps helps ensure a smooth review and merge process.
Contribution Steps
- Find an open issue that matches your interests or skills.
- Request assignment by commenting on the issue.
- Fork the repository to your GitHub account.
- Create a new feature or documentation branch.
- Make your changes and test them.
- Submit a Pull Request.
- Wait for CI checks and maintainer review.
- Once approved, your contribution will be merged.
Contributing
We welcome contributions from everyone — developers, designers, writers, and testers!
How to Contribute
- Browse open issues or create a new one
- Comment on the issue to request assignment (bot assigns automatically)
- Follow the Development Workflow above
- Read CONTRIBUTING.md for detailed guidelines
- Follow CODE_OF_CONDUCT.md
- Follow TEST_GUIDELINES.md when adding tests
Types of Contributions
| Type |
Examples |
| Bug fixes |
Fix crashes, incorrect behaviour, UI bugs |
| New features |
New screens, API endpoints, integrations |
| Content |
Health articles, translations |
| Documentation |
README, guides, code comments |
| UI/UX |
Design improvements, accessibility |
| Tests |
Unit tests, E2E tests, coverage improvements |
Programs Participated In
 |
GirlScript Summer of Code 2026
3-month open source program empowering next-generation developers through real-world contributions |
 |
IEEE IGDTUW Open Source Week
November 12-18 |
 |
Vultr Cloud Innovate Hackathon
Build innovative solutions using Vultr cloud |
|
GirlScript Summer of Code 2024
3-month open source program for beginners |
Blogs & Resources
Our Contributors
Thank you for contributing to UltimateHealth
We appreciate every contribution — big or small.
README 内容过长，已截取前 64 KB。完整内容请前往 GitHub 仓库查看。
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)
![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)
评论