Skip to content
/ AMA-Maternal-Health-Assistant Public

🤰 AI-powered maternal health companion for Ethiopian mothers. Features Amharic voice assistant, symptom checker, pregnancy tracking, and offline-capable health guidance. Built with Flutter & NestJS.

0 stars 0 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

davegerim/AMA-Maternal-Health-Assistant

BranchesTags

Repository files navigation

🤰 AMA Maternal Health Assistant

Senay Med - An AI-powered maternal health companion app designed for Ethiopian mothers, providing offline-capable health guidance, symptom checking, and voice assistance in Amharic.

Flutter NestJS TypeScript License

📋 Table of Contents

🌟 Overview

AMA Maternal Health Assistant is a comprehensive mobile health application designed to support pregnant women in Ethiopia, particularly in rural areas with limited access to healthcare. The app combines modern AI technology with culturally sensitive health information to provide:

  • 24/7 AI-powered health guidance in Amharic
  • Offline-capable symptom checking and health assessments
  • Voice assistant for hands-free interaction
  • Pregnancy journey tracking with week-by-week guidance
  • Digital health passport with QR code sharing
  • Community support and educational resources
  • Emergency contact and risk assessment features

Why AMA?

  • 🌍 Culturally Adapted: Designed specifically for Ethiopian mothers with Amharic language support
  • 📱 Offline-First: Core features work without internet connectivity
  • 🤖 AI-Powered: Leverages GPT-3.5, Whisper, and xAI Grok for intelligent responses
  • 🔒 Privacy-Focused: Secure data handling with local processing options
  • 🎯 Evidence-Based: Medical information based on WHO and Ethiopian health guidelines

✨ Features

🏥 Core Health Features

1. AI Symptom Checker

  • Analyze pregnancy-related symptoms using xAI Grok-3
  • Risk level assessment (Low/Medium/High)
  • Personalized recommendations based on trimester
  • Urgency indicators for when to seek medical help
  • Symptom history tracking

2. Voice Assistant

  • Speech-to-Text: Amharic voice recognition using OpenAI Whisper
  • AI Responses: Context-aware maternal health guidance
  • Text-to-Speech: Natural Amharic voice synthesis
  • Quick Questions: Pre-configured common queries
  • Conversation History: Track past interactions

3. Pregnancy Journey Tracker

  • Week-by-week pregnancy progress
  • Trimester-specific guidance and tips
  • Baby development milestones
  • Appointment reminders
  • Weight and vital signs tracking

4. Digital Health Passport

  • Comprehensive health profile
  • Medical history and conditions
  • Blood pressure and vital signs
  • QR code for easy sharing with healthcare providers
  • Secure data encryption

5. Emergency Features

  • Quick access to emergency contacts
  • Hospital locator (offline-capable)
  • Warning signs recognition
  • One-tap emergency call
  • Location sharing capabilities

6. Community Support

  • Educational articles and videos
  • Peer support forums
  • Expert Q&A sessions
  • Cultural health practices
  • Nutrition and exercise guides

🔐 Authentication & Security

  • JWT-based authentication with refresh tokens
  • Email verification with OTP
  • Password reset functionality
  • Role-based access control
  • Secure API key management
  • Data encryption at rest and in transit

🌐 Multi-Language Support

  • Amharic (አማርኛ) - Primary
  • English - Secondary
  • Oromo (Afaan Oromoo) - Planned

🏗️ Architecture

System Architecture

┌─────────────────────────────────────────────────────────────┐
│                     Flutter Mobile App                       │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │   Screens    │  │  Providers   │  │   Services   │     │
│  │  (UI Layer)  │  │  (State Mgmt)│  │ (Business)   │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
└─────────────────────────────────────────────────────────────┘
                            │
                            │ HTTP/REST API
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                    NestJS Backend API                        │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │ Controllers  │  │   Services   │  │  Entities    │     │
│  │  (Routes)    │  │  (Logic)     │  │  (Models)    │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
└─────────────────────────────────────────────────────────────┘
                            │
                            │ TypeORM
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                    SQLite Database                           │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │    Users     │  │   Profiles   │  │ Assessments  │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
└─────────────────────────────────────────────────────────────┘

External AI Services:
┌──────────────┐  ┌──────────────┐  ┌──────────────┐
│  OpenAI API  │  │   xAI Grok   │  │ Hugging Face │
│ (Whisper/GPT)│  │  (Symptom)   │  │   (Backup)   │
└──────────────┘  └──────────────┘  └──────────────┘

Data Flow

  1. User Interaction → Flutter UI captures input
  2. State Management → Provider updates app state
  3. Service Layer → Business logic processing
  4. API Communication → HTTP requests to backend
  5. Backend Processing → NestJS controllers handle requests
  6. AI Integration → External AI APIs for intelligent features
  7. Database → SQLite for data persistence
  8. Response → Data flows back through layers to UI

🛠️ Tech Stack

Frontend (Mobile App)

Technology Purpose Version
Flutter Cross-platform mobile framework 3.0+
Dart Programming language 3.0+
Provider State management 6.0.5
Dio HTTP client 5.3.2
Flutter TTS Text-to-speech 3.8.5
Flutter Sound Audio recording 9.2.13
Just Audio Audio playback 0.9.46
QR Flutter QR code generation 4.1.0
Shared Preferences Local storage 2.2.2

Backend (API Server)

Technology Purpose Version
NestJS Node.js framework 9.0+
TypeScript Programming language 5.0+
TypeORM ORM for database 0.3.20
SQLite Database 5.1.7
Passport JWT Authentication 4.0.1
Bcrypt Password hashing 5.1.1
Nodemailer Email service 7.0.5
Swagger API documentation 7.4.0
Class Validator DTO validation 0.14.1

AI Services

Service Purpose Features
OpenAI Whisper Speech-to-text Amharic voice recognition
OpenAI GPT-3.5 Text generation Conversational AI responses
OpenAI TTS Text-to-speech Natural voice synthesis
xAI Grok-3 Symptom analysis Medical symptom assessment
Hugging Face Backup AI Alternative AI models
Addis Assistant Local AI Ethiopian-focused AI service

🚀 Getting Started

Prerequisites

  • Flutter SDK 3.0 or higher
  • Node.js 18.x or higher
  • npm or yarn
  • Git
  • Android Studio or Xcode (for mobile development)
  • PostgreSQL (optional, for production)

Installation

1. Clone the Repository

git clone https://github.com/davegerim/AMA-Maternal-Health-Assistant.git
cd AMA-Maternal-Health-Assistant

2. Setup Flutter App

cd ama_maternal_health

# Install dependencies
flutter pub get

# Copy environment template
copy .env.example .env

# Edit .env and add your API keys
# OPENAI_API_KEY=your_openai_key_here
# HUGGINGFACE_API_TOKEN=your_huggingface_token_here

# Run the app
flutter run

3. Setup NestJS Backend

cd NestJS-backend-with-authentication

# Install dependencies
npm install

# Copy environment template
copy .env.example .env

# Edit .env and add your configuration
# XAI_API_KEY=your_xai_key_here
# POSTGRES_PASSWORD=your_password_here

# Run database migrations
npm run build

# Start the server
npm run start:dev

The backend will be available at http://localhost:3000 API documentation at http://localhost:3000/api

Configuration

Flutter App Configuration

Edit ama_maternal_health/lib/services/api_config.dart:

class ApiConfig {
  static const String baseUrl = 'http://your-backend-url:3000/api';
  // Other configurations...
}

Backend Configuration

Edit NestJS-backend-with-authentication/.env:

# Database
POSTGRES_HOST=127.0.0.1
POSTGRES_PORT=5432
POSTGRES_USER=postgres
POSTGRES_PASSWORD=your_password
POSTGRES_DATABASE=ama_maternal_health

# Server
PORT=3000
MODE=DEV

# API Keys
XAI_API_KEY=your_xai_key

📁 Project Structure

Flutter App Structure

ama_maternal_health/
├── lib/
│   ├── main.dart                 # App entry point
│   ├── models/                   # Data models
│   │   └── user_profile.dart
│   ├── providers/                # State management
│   │   ├── pregnancy_provider.dart
│   │   ├── health_provider.dart
│   │   ├── voice_provider.dart
│   │   └── community_provider.dart
│   ├── screens/                  # UI screens
│   │   ├── splash_screen.dart
│   │   ├── login_screen.dart
│   │   ├── home_screen.dart
│   │   ├── symptom_checker_screen.dart
│   │   ├── voice_assistant_screen.dart
│   │   ├── pregnancy_journey_screen.dart
│   │   ├── health_passport_screen.dart
│   │   └── emergency_screen.dart
│   ├── services/                 # Business logic
│   │   ├── api_service.dart
│   │   ├── ai_voice_service.dart
│   │   ├── huggingface_service.dart
│   │   ├── audio_manager.dart
│   │   └── health_passport_service.dart
│   ├── widgets/                  # Reusable components
│   │   ├── health_status_card.dart
│   │   ├── pregnancy_progress_card.dart
│   │   └── quick_action_card.dart
│   └── utils/                    # Utilities
│       └── theme.dart
├── assets/                       # Static assets
│   ├── images/
│   ├── fonts/
│   └── animations/
├── .env                          # Environment variables (not in git)
├── .env.example                  # Environment template
└── pubspec.yaml                  # Dependencies

Backend Structure

NestJS-backend-with-authentication/
├── src/
│   ├── main.ts                   # App entry point
│   ├── app.module.ts             # Root module
│   ├── auth/                     # Authentication module
│   │   ├── auth.controller.ts
│   │   ├── auth.service.ts
│   │   ├── jwt.strategy.ts
│   │   └── guards/
│   ├── user/                     # User management
│   │   ├── user.controller.ts
│   │   ├── user.service.ts
│   │   └── entities/
│   ├── maternal-health/          # Maternal health features
│   │   ├── maternal-health.controller.ts
│   │   ├── maternal-health.service.ts
│   │   ├── symptom-checker.service.ts
│   │   ├── dto/
│   │   └── entities/
│   ├── otp/                      # OTP verification
│   │   ├── otp.controller.ts
│   │   └── otp.service.ts
│   ├── email/                    # Email service
│   │   └── email.service.ts
│   └── profile/                  # User profiles
│       ├── profile.controller.ts
│       └── profile.service.ts
├── .env                          # Environment variables (not in git)
├── .env.example                  # Environment template
├── package.json                  # Dependencies
└── tsconfig.json                 # TypeScript config

📚 API Documentation

Base URL

http://localhost:3000/api

Authentication Endpoints

Register User

POST /api/auth/register
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "SecurePass123!",
  "firstName": "Abebe",
  "lastName": "Kebede",
  "phoneNumber": "+251911234567"
}

Login

POST /api/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "SecurePass123!"
}

Response:
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "uuid",
    "email": "user@example.com",
    "firstName": "Abebe"
  }
}

Maternal Health Endpoints

Create Maternal Profile

POST /api/maternal-health/profile
Authorization: Bearer {token}
Content-Type: application/json

{
  "lastPeriodDate": "2024-01-15",
  "dueDate": "2024-10-22",
  "pregnancyWeek": 12,
  "bloodType": "O+",
  "weight": 65,
  "height": 165,
  "systolicBP": 120,
  "diastolicBP": 80,
  "healthIssues": ["None"]
}

Analyze Symptoms

POST /api/maternal-health/symptom-checker
Authorization: Bearer {token}
Content-Type: application/json

{
  "symptoms": "Experiencing headache and dizziness",
  "selectedSymptoms": ["Headache", "Dizziness"],
  "pregnancyWeek": 24,
  "trimester": "Second"
}

Response:
{
  "riskLevel": "Medium",
  "analysis": "These symptoms may indicate...",
  "recommendations": [
    "Monitor your blood pressure",
    "Stay hydrated",
    "Contact your healthcare provider if symptoms worsen"
  ],
  "urgency": "Within 24 hours",
  "whenToSeekHelp": "Contact your doctor if..."
}

Get Pregnancy Progress

GET /api/maternal-health/pregnancy-progress
Authorization: Bearer {token}

Response:
{
  "currentWeek": 24,
  "daysUntilDue": 112,
  "progressPercentage": 60,
  "trimester": "Second"
}

Complete API Documentation

Visit http://localhost:3000/api when the backend is running to access the interactive Swagger documentation.

🤖 AI Integration

OpenAI Integration

Whisper (Speech-to-Text)

// Convert Amharic speech to text
final transcription = await AIVoiceService.transcribeAudio(audioData);

GPT-3.5 (Text Generation)

// Generate maternal health response
final response = await AIVoiceService.generateMedicalResponse(
  userInput,
  language: 'am'
);

TTS (Text-to-Speech)

// Convert text to Amharic speech
final audioData = await AIVoiceService.synthesizeSpeech(text);

xAI Grok Integration

// Analyze symptoms using Grok-3
const analysis = await symptomCheckerService.analyzeSymptoms({
  symptoms: 'headache and nausea',
  pregnancyWeek: 20,
  trimester: 'Second'
});

Hugging Face Integration

// Backup AI service
final response = await HuggingFaceService.generateResponse(userInput);
final audio = await HuggingFaceService.synthesizeSpeech(text);

AI Service Fallback Chain

  1. Primary: OpenAI GPT-3.5 / xAI Grok
  2. Secondary: Hugging Face models
  3. Tertiary: Addis Assistant API
  4. Fallback: Local pre-configured responses

🔒 Security

Security Measures Implemented

✅ API Key Protection

  • Environment variables for all API keys
  • Never committed to version control
  • Secure key rotation procedures

✅ Authentication & Authorization

  • JWT-based authentication
  • Refresh token mechanism
  • Role-based access control
  • Password hashing with bcrypt

✅ Data Protection

  • HTTPS/TLS encryption in transit
  • Encrypted local storage
  • Secure database connections
  • Input validation and sanitization

✅ Privacy

  • GDPR-compliant data handling
  • User consent management
  • Data minimization principles
  • Right to deletion

Environment Variables

Never commit these files:

  • .env
  • .env.local
  • .env.production
  • Any file containing API keys

Always use:

  • .env.example as a template
  • Environment variable loading
  • Secure key management services

API Key Management

  1. Obtain API Keys:

  2. Store Securely:

    # Add to .env file (never commit!)
OPENAI_API_KEY=your_key_here
XAI_API_KEY=your_key_here
HUGGINGFACE_API_TOKEN=your_token_here

  3. Rotate Regularly:

    • Revoke old keys
    • Generate new keys
    • Update environment variables
    • Test thoroughly

🧪 Testing

Flutter App Testing

# Run unit tests
flutter test

# Run integration tests
flutter test integration_test/

# Run with coverage
flutter test --coverage

Backend Testing

# Run unit tests
npm run test

# Run e2e tests
npm run test:e2e

# Run with coverage
npm run test:cov

Manual Testing

Use the built-in test screens:

  • Voice Assistant Test Screen
  • API Connection Test
  • Symptom Checker Test
  • Health Passport Test

🌍 Localization

Supported Languages

  • Amharic (አማርኛ): Primary language
  • English: Secondary language
  • Oromo (Afaan Oromoo): Planned

Adding Translations

  1. Add translations to language files
  2. Update locale configurations
  3. Test with different locales
  4. Verify RTL support (if needed)

📱 Deployment

Flutter App Deployment

Android

flutter build apk --release
flutter build appbundle --release

iOS

flutter build ios --release

Backend Deployment

Using Docker

docker build -t ama-backend .
docker run -p 3000:3000 ama-backend

Using PM2

npm run build
pm2 start dist/main.js --name ama-backend

🤝 Contributing

We welcome contributions! Please follow these steps:

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature/amazing-feature
  3. Commit your changes: git commit -m 'Add amazing feature'
  4. Push to the branch: git push origin feature/amazing-feature
  5. Open a Pull Request

Contribution Guidelines

  • Follow the existing code style
  • Write meaningful commit messages
  • Add tests for new features
  • Update documentation
  • Ensure all tests pass

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👥 Team

📞 Support

🙏 Acknowledgments

  • Ethiopian Ministry of Health for guidelines
  • WHO for maternal health standards
  • OpenAI for AI capabilities
  • xAI for Grok integration
  • Flutter and NestJS communities
  • All contributors and testers

🗺️ Roadmap

Phase 1 (Current)

  • ✅ Core maternal health features
  • ✅ AI voice assistant
  • ✅ Symptom checker
  • ✅ Health passport

Phase 2 (Q1 2025)

  • 🔄 Telemedicine integration
  • 🔄 Hospital network integration
  • 🔄 Advanced analytics
  • 🔄 Multi-language expansion

Phase 3 (Q2 2025)

  • 📋 Wearable device integration
  • 📋 Community health worker portal
  • 📋 Offline AI models
  • 📋 Advanced risk prediction

⚠️ Disclaimer

This application is designed to provide health information and support, but it is not a substitute for professional medical advice, diagnosis, or treatment. Always seek the advice of your physician or other qualified health provider with any questions you may have regarding a medical condition.

Made with ❤️ for Ethiopian Mothers

⬆ Back to Top

About

🤰 AI-powered maternal health companion for Ethiopian mothers. Features Amharic voice assistant, symptom checker, pregnancy tracking, and offline-capable health guidance. Built with Flutter & NestJS.

Topics

healthcare openai flutter amharic symptom-checker nestjs maternal-health voice-assistant-ai pregnancy-tracker offline-first-app

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages