Health Watchers

Note: Replace OWNER in the badge URLs below with your GitHub username or organization name.

A HIPAA-compliant healthcare management platform built with Next.js, Express, and Stellar blockchain integration for secure patient data management and payment processing.

Features

• 🏥 Patient management with comprehensive health records
• 📅 Medical encounter tracking and documentation
• 💳 Blockchain-based payment processing via Stellar
• 🔐 HIPAA-compliant authentication and authorization
• 🌐 Internationalization support (English, French)
• 🎨 Modern, accessible UI with Tailwind CSS
• 🔄 Real-time data synchronization with React Query

Tech Stack

• Frontend: Next.js 14, React 18, TypeScript, Tailwind CSS
• Backend: Express.js, Node.js, TypeScript
• Database: MongoDB
• Blockchain: Stellar (testnet/mainnet)
• Authentication: JWT with refresh tokens
• Monorepo: npm workspaces with Turbo

Getting Started

Prerequisites

• Node.js >= 18.0.0
• npm 10.9.2
• Docker and Docker Compose

Quick Start — MongoDB only (recommended for local dev)

No local MongoDB installation required. Spin up just the database:

# 1. Clone the repository
git clone https://github.com/OWNER/health-watchers.git
cd health-watchers

# 2. Copy environment configuration
cp .env.example .env

# 3. Start MongoDB (and optional mongo-express UI on :8081)
docker-compose -f docker-compose.dev.yml up -d

# 4. Install dependencies and start the API
npm install
npm run dev --workspace=api

The default MONGO_URI=mongodb://localhost:27017/health_watchers in .env.example connects directly to the containerized MongoDB — no credentials needed for local dev.

To stop:

docker-compose -f docker-compose.dev.yml down

5-Minute Quickstart — Full Stack with Docker Compose

Runs all services (API, web, stellar-service, MongoDB) in containers:

# 1. Clone the repository
git clone https://github.com/OWNER/health-watchers.git
cd health-watchers

# 2. Copy environment configuration
cp .env.example .env

# 3. Start all services
docker-compose up -d

# 4. Access the application
# Web UI: http://localhost:3000
# API: http://localhost:3001

To stop all services:

docker-compose down

Manual Setup

If you prefer to run services individually:

# 1. Install dependencies
npm install

# 2. Set up environment variables
cp .env.example .env
# Edit .env with your configuration

# 3. Start MongoDB (if not using Docker)
# macOS: brew services start mongodb-community
# Linux: sudo systemctl start mongod
# Windows: net start MongoDB

# 4. Seed the database (optional)
npm run seed

# 5. Start development servers
npm run dev

This will start:

• Web app on http://localhost:3000
• API server on http://localhost:3001
• Stellar service on http://localhost:3002

Project Structure

health-watchers/
├── apps/
│   ├── api/              # Express.js REST API
│   ├── web/              # Next.js frontend application
│   └── stellar-service/  # Stellar blockchain integration
├── packages/             # Shared packages (types, utils)
├── scripts/              # Database seeding and utilities
├── .env.example          # Environment configuration template
└── docker-compose.yml    # Docker orchestration

Development

Available Scripts

npm run dev      # Start all apps in development mode
npm run build    # Build all apps for production
npm run start    # Start all apps in production mode
npm run lint     # Run linting across all apps
npm run seed     # Seed database with sample data

Environment Variables

See .env.example for a complete list of required environment variables. Key variables include:

• MONGO_URI - MongoDB connection string
• JWT_ACCESS_TOKEN_SECRET - JWT signing secret
• STELLAR_NETWORK - Stellar network (testnet/mainnet)
• GEMINI_API_KEY - Google Gemini API for AI features
• NEXT_PUBLIC_API_URL - API endpoint for frontend

Security & Compliance

Health Watchers is designed with HIPAA compliance in mind:

• 🔒 End-to-end encryption for sensitive data
• 🔑 Secure JWT-based authentication
• 📝 Comprehensive audit logging
• 🔄 Regular security updates and dependency scanning
• 🛡️ Input validation and sanitization
• 🔐 Secrets management with AWS Secrets Manager support

For detailed security guidelines, see SECURITY.md.

Testing

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch

Deployment

Docker Production Deployment

# Build production images
docker-compose -f docker-compose.prod.yml build

# Start production services
docker-compose -f docker-compose.prod.yml up -d

Manual Production Deployment

# Build all applications
npm run build

# Start production servers
npm run start

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

License

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

Support

For questions, issues, or feature requests:

• 📧 Email: support@healthwatchers.com
• 🐛 Issues: GitHub Issues
• 📖 Documentation: Wiki

Acknowledgments

• Built with Next.js
• Blockchain integration powered by Stellar
• UI components inspired by modern design systems
• HIPAA compliance guidance from healthcare industry standards

---

Made with ❤️ by the Health Watchers team