From 8e46a95ae4849de94fdf9490a8d06bbab510b180 Mon Sep 17 00:00:00 2001 From: Kalema Kosea Date: Tue, 24 Mar 2026 09:48:25 +0300 Subject: [PATCH] Rewrite README with fixes and improved structure --- README.md | 725 ++++++++++++++---------------------------------------- 1 file changed, 185 insertions(+), 540 deletions(-) diff --git a/README.md b/README.md index ccc78b0..91faf72 100644 --- a/README.md +++ b/README.md @@ -2,652 +2,297 @@ A comprehensive health informatics platform backend built with Django, designed specifically for healthcare management in Africa. +--- + ## πŸ₯ Project Overview -OpenCare-Africa is a robust, scalable backend system for managing healthcare operations, patient records, health worker management, and health facility operations. The system is built with modern Django practices and includes comprehensive API endpoints for integration with frontend applications. +OpenCare-Africa is a robust, scalable backend system for managing healthcare operations, patient records, health worker management, and facility operations. The system follows modern Django best practices and provides comprehensive API endpoints for seamless frontend integration. + +--- ## ✨ Features ### Core Functionality -- **User Management**: Comprehensive user roles and permissions for healthcare workers -- **Patient Management**: Complete patient lifecycle management with medical history -- **Health Facility Management**: Facility operations, services, and resource management -- **Health Records**: Comprehensive medical records with FHIR compliance -- **Analytics & Reporting**: Health metrics, disease outbreak tracking, and performance analytics -- **API-First Design**: RESTful API with OpenAPI/Swagger documentation + +* **User Management**: Role-based access and permissions for healthcare workers +* **Patient Management**: End-to-end patient lifecycle management with medical history +* **Health Facility Management**: Facility operations, services, and resources +* **Health Records**: Detailed medical records with FHIR compliance +* **Analytics & Reporting**: Disease tracking, performance metrics, and insights +* **API-First Design**: RESTful APIs with OpenAPI/Swagger documentation ### Technical Features -- **Django 4.2+**: Modern Django with best practices -- **PostgreSQL**: Robust database with healthcare-optimized schemas -- **Redis**: Caching and session management -- **Celery**: Background task processing -- **Docker**: Containerized deployment -- **JWT Authentication**: Secure API authentication -- **Health Checks**: System monitoring and diagnostics + +* **Django 4.2+**: Modern Django implementation +* **PostgreSQL**: Reliable and scalable database +* **Redis**: Caching and session management +* **Celery**: Background task processing +* **Docker**: Containerized deployment +* **JWT Authentication**: Secure API access +* **Health Checks**: System monitoring and diagnostics + +--- ## πŸ—οΈ Architecture ``` OpenCare-Africa/ -β”œβ”€β”€ apps/ # Django applications -β”‚ β”œβ”€β”€ core/ # Core models and utilities -β”‚ β”œβ”€β”€ patients/ # Patient management -β”‚ β”œβ”€β”€ health_workers/ # Healthcare personnel management -β”‚ β”œβ”€β”€ facilities/ # Health facility operations -β”‚ β”œβ”€β”€ records/ # Medical records management -β”‚ β”œβ”€β”€ analytics/ # Health analytics and reporting -β”‚ └── api/ # API endpoints and viewsets -β”œβ”€β”€ config/ # Project configuration -β”‚ β”œβ”€β”€ settings/ # Environment-specific settings -β”‚ β”œβ”€β”€ urls.py # Main URL configuration -β”‚ └── celery.py # Celery configuration -β”œβ”€β”€ templates/ # HTML templates -β”œβ”€β”€ static/ # Static files -β”œβ”€β”€ media/ # User-uploaded files -β”œβ”€β”€ docs/ # Documentation -└── scripts/ # Database and deployment scripts +β”œβ”€β”€ apps/ +β”‚ β”œβ”€β”€ core/ +β”‚ β”œβ”€β”€ patients/ +β”‚ β”œβ”€β”€ health_workers/ +β”‚ β”œβ”€β”€ facilities/ +β”‚ β”œβ”€β”€ records/ +β”‚ β”œβ”€β”€ analytics/ +β”‚ └── api/ +β”œβ”€β”€ config/ +β”‚ β”œβ”€β”€ settings/ +β”‚ β”œβ”€β”€ urls.py +β”‚ └── celery.py +β”œβ”€β”€ templates/ +β”œβ”€β”€ static/ +β”œβ”€β”€ media/ +β”œβ”€β”€ docs/ +└── scripts/ ``` +--- + ## πŸš€ Quick Start ### Prerequisites -- **Docker & Docker Compose** (recommended for all environments) -- Python 3.11+ (only needed for local development without Docker) -- PostgreSQL 15+ (included in Docker setup) -- Redis 7+ (included in Docker setup) - -### 🐳 Docker Setup (Recommended) - -This is the **recommended** way to run OpenCare-Africa as it ensures consistency across all environments. - -1. **Clone the repository** - ```bash - git clone https://github.com/bos-com/OpenCare-Africa.git - cd OpenCare-Africa - ``` - -2. **Set up environment variables** - ```bash - # Copy environment template - cp env.example .env - - # The .env file is already configured for Docker - # No changes needed unless you want to customize settings - ``` - -3. **Build and start all services** - ```bash - # Build Docker images - docker-compose build - - # Start all services (database, Redis, web app, Celery) - docker-compose up -d - ``` - -4. **Run database migrations** - ```bash - docker-compose exec web python manage.py migrate - ``` - -5. **Create superuser (optional)** - ```bash - docker-compose exec web python manage.py createsuperuser - ``` - -6. **Verify the installation** - ```bash - # Check service status - docker-compose ps - - # Test the health endpoint - curl http://localhost:8000/health/ - - # Test the web interface - open http://localhost:8000/ - ``` - -7. **Access the application** - - **Web Interface**: http://localhost:8000 - - **Admin Panel**: http://localhost:8000/admin - - **API Documentation**: http://localhost:8000/api/docs/ - - **Health Check**: http://localhost:8000/health/ - -## πŸ“˜ Viewing API Docs - -- Start the stack via Docker or local development, then browse to http://localhost:8000/api/docs/ for interactive OpenAPI documentation. -- Review sanitized response expectations and logging rules in [`docs/error-handling.md`](docs/error-handling.md) before exposing new endpoints. -- Extend automated tests to cover both happy-path and error scenarios when updating API behavior; see the error-handling guide for recommendations. - -### 🐳 Docker Services Overview - -The Docker setup includes the following services: - -| Service | Port | Purpose | -|---------|------|---------| -| **web** | 8000 | Django web application | -| **db** | 5432 | PostgreSQL database | -| **redis** | 6379 | Redis cache and Celery broker | -| **celery** | - | Background task processor | -| **celery-beat** | - | Scheduled task scheduler | -| **nginx** | 80 | Reverse proxy (production) | -| **metabase** | 3000 | Analytics dashboard | -| **superset** | 8088 | Business intelligence platform | - -### πŸš€ Quick Docker Commands -```bash -# Start all services -docker-compose up -d +* Docker & Docker Compose (recommended) +* Python 3.11+ (for local development) +* PostgreSQL 15+ (included in Docker) +* Redis 7+ (included in Docker) -# View service status -docker-compose ps +--- -# View logs -docker-compose logs -f web +## 🐳 Docker Setup (Recommended) -# Stop all services -docker-compose down +This is the recommended way to run OpenCare-Africa, as it ensures consistency across all environments. -# Restart a specific service -docker-compose restart web +### 1. Clone the repository -# Execute Django commands -docker-compose exec web python manage.py migrate -docker-compose exec web python manage.py createsuperuser -docker-compose exec web python manage.py shell +```bash +git clone https://github.com/bos-com/OpenCare-Africa.git +cd OpenCare-Africa ``` -### πŸ› οΈ Local Development Setup (Alternative) - -If you prefer to run the application locally without Docker: - -1. **Clone the repository** - ```bash - git clone https://github.com/bos-com/OpenCare-Africa.git - cd OpenCare-Africa - ``` - -2. **Set up Python virtual environment** - ```bash - # Create virtual environment - python3 -m venv venv - - # Activate virtual environment - source venv/bin/activate # On Windows: venv\Scripts\activate - - # Upgrade pip - pip install --upgrade pip - ``` - -3. **Set up environment variables** - ```bash - # Copy environment template - cp env.example .env - - # Update .env for local development - # Change DB_HOST=localhost and REDIS_HOST=localhost - ``` - -4. **Install dependencies** - ```bash - # Install production dependencies - pip install -r requirements.txt - - # Install development dependencies (optional) - pip install -r requirements-dev.txt - ``` - -5. **Set up the database** - ```bash - # For development, SQLite is used by default - # No additional database setup required - - # Run migrations - python manage.py migrate - ``` - -6. **Create superuser (optional)** - ```bash - python manage.py createsuperuser - ``` - -7. **Run the development server** - ```bash - python manage.py runserver - ``` - -8. **Verify the installation** - ```bash - # Test the API health endpoint - curl http://localhost:8000/health/ - - # Test the web interface - open http://localhost:8000/ - ``` - -## πŸ“Š API Documentation - -The API is fully documented using OpenAPI/Swagger: - -- **Swagger UI**: `/api/docs/` -- **ReDoc**: `/api/redoc/` -- **OpenAPI Schema**: `/api/schema/` - -### Key API Endpoints - -- **Authentication**: `/api/v1/auth/` -- **Patients**: `/api/v1/patients/` -- **Health Workers**: `/api/v1/health-workers/` -- **Facilities**: `/api/v1/facilities/` -- **Health Records**: `/api/v1/records/` -- **Analytics**: `/api/v1/analytics/` -- **Appointments**: `/api/v1/appointments/` - -## πŸ—„οΈ Database Schema +### 2. Set up environment variables -### Core Models -- **User**: Extended user model with healthcare worker profiles -- **Location**: Hierarchical geographic location management -- **HealthFacility**: Health facility information and services -- **AuditTrail**: Comprehensive audit logging +```bash +cp env.example .env +``` -### Patient Models -- **Patient**: Complete patient information and demographics -- **PatientVisit**: Patient visit tracking and scheduling -- **PatientMedicalHistory**: Medical history and conditions +The `.env` file is already configured for Docker. No changes are needed unless you want to customize settings. -### Healthcare Models -- **HealthWorkerProfile**: Extended healthcare worker profiles -- **ProfessionalQualification**: Qualifications and certifications -- **WorkSchedule**: Work schedules and availability -- **PerformanceEvaluation**: Performance tracking and reviews +### 3. Build and start services -### Facility Models -- **FacilityService**: Services offered by health facilities -- **FacilityStaff**: Staff management and assignments -- **FacilityEquipment**: Medical equipment tracking -- **FacilityInventory**: Medical supplies and inventory +```bash +docker-compose build +docker-compose up -d +``` -### Records Models -- **HealthRecord**: Comprehensive medical records -- **VitalSigns**: Patient vital signs and measurements -- **Medication**: Prescription and medication management -- **LaboratoryTest**: Lab test results and interpretation -- **ImagingStudy**: Medical imaging results - -### Analytics Models -- **HealthMetrics**: Health KPIs and metrics -- **DiseaseOutbreak**: Disease outbreak tracking -- **HealthReport**: Automated health reports -- **PatientAnalytics**: Patient-specific analytics +### 4. Run migrations -## πŸ”§ Configuration +```bash +docker-compose exec web python manage.py migrate +``` -### Environment Variables +### 5. Create a superuser (optional) ```bash -# Django Configuration -SECRET_KEY=your-secret-key-here -DEBUG=True -ALLOWED_HOSTS=localhost,127.0.0.1 - -# Database Configuration -DB_ENGINE=django.db.backends.postgresql -DB_NAME=opencare_africa -DB_USER=opencare_user -DB_PASSWORD=opencare_password -DB_HOST=localhost -DB_PORT=5432 +docker-compose exec web python manage.py createsuperuser +``` -# Redis Configuration -REDIS_HOST=localhost -REDIS_PORT=6379 -REDIS_DB=0 +### 6. Verify installation -# JWT Configuration -JWT_ACCESS_TOKEN_LIFETIME=5 -JWT_REFRESH_TOKEN_LIFETIME=1 +```bash +docker-compose ps +curl http://localhost:8000/health/ ``` -### Settings Files +### 7. Access the application -- `config/settings/base.py`: Base configuration -- `config/settings/development.py`: Development environment -- `config/settings/production.py`: Production environment -- `config/settings/test.py`: Testing environment +* Web: [http://localhost:8000](http://localhost:8000) +* Admin: [http://localhost:8000/admin](http://localhost:8000/admin) +* API Docs: [http://localhost:8000/api/docs/](http://localhost:8000/api/docs/) -## πŸ§ͺ Testing +--- -```bash -# Run all tests -python manage.py test +## πŸ“˜ API Documentation -# Run tests with coverage -coverage run --source='.' manage.py test -coverage report -coverage html +* Swagger UI: `/api/docs/` +* ReDoc: `/api/redoc/` +* Schema: `/api/schema/` -# Run specific app tests -python manage.py test apps.patients -python manage.py test apps.core -``` +### Key Endpoints -## πŸ“ˆ Performance & Monitoring +* `/api/v1/auth/` +* `/api/v1/patients/` +* `/api/v1/health-workers/` +* `/api/v1/facilities/` +* `/api/v1/records/` +* `/api/v1/analytics/` -### Health Checks -- Database connectivity -- Redis connectivity -- Storage availability -- System resources +--- -### Monitoring -- Django Debug Toolbar (development) -- Sentry integration (production) -- Custom health metrics -- Performance analytics +## πŸ› οΈ Local Development Setup -### Caching -- Redis-based caching -- Database query optimization -- Static file caching -- API response caching +If you prefer to run the application locally without Docker, follow these steps: -## πŸš€ Deployment +### 1. Create a virtual environment -### Production Checklist -- [ ] Set `DEBUG=False` -- [ ] Configure production database -- [ ] Set up SSL/TLS certificates -- [ ] Configure static file serving -- [ ] Set up monitoring and logging -- [ ] Configure backup strategies -- [ ] Set up CI/CD pipelines - -### Docker Production ```bash -# Build production image -docker build -t opencare-africa:latest . - -# Run with production settings -docker run -e DJANGO_SETTINGS_MODULE=config.settings.production opencare-africa:latest +python3 -m venv venv +source venv/bin/activate # Windows: venv\Scripts\activate ``` -## πŸ”’ Security Features - -- JWT-based authentication -- Role-based access control -- Comprehensive audit logging -- Input validation and sanitization -- CORS configuration -- Rate limiting (configurable) -- Secure password policies - -## πŸ“š Documentation +### 2. Install dependencies -- **API Documentation**: Built-in Swagger/OpenAPI docs -- **Code Documentation**: Comprehensive docstrings -- **Admin Interface**: Django admin for data management -- **User Guides**: Available in `/docs/` directory -- **Patient Records**: See [`docs/patient-records.md`](docs/patient-records.md) for CRUD usage and security notes -- **Audit Logging**: See [`docs/audit-logs.md`](docs/audit-logs.md) for PHI access tracking requirements -- **Appointments**: See [`docs/appointments.md`](docs/appointments.md) for scheduling API usage and safeguards - -## 🀝 Contributing - -1. Fork the repository -2. Create a feature branch -3. Make your changes -4. Add tests for new functionality -5. Ensure all tests pass -6. Submit a pull request - -### Development Guidelines -- Follow PEP 8 style guidelines -- Write comprehensive docstrings -- Include tests for new features -- Update documentation as needed -- Use meaningful commit messages +```bash +pip install --upgrade pip +pip install -r requirements.txt +pip install -r requirements-dev.txt # optional +``` -## πŸ“„ License +### 3. Configure environment -This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. +```bash +cp env.example .env +``` -## πŸ”§ Troubleshooting +Update DB and Redis settings for local use. -### Docker-Specific Issues +### 4. Run migrations -#### 1. Docker Build Failures -**Issue**: `docker-compose build` fails with errors -**Solution**: ```bash -# Clean up Docker cache and rebuild -docker-compose down -docker system prune -f -docker-compose build --no-cache - -# Check Docker logs for specific errors -docker-compose logs web +python manage.py migrate ``` -#### 2. Port Conflicts -**Issue**: `Port is already allocated` or `Address already in use` -**Solution**: -```bash -# Check what's using the port -sudo netstat -tulpn | grep :8000 +### 5. Start server -# Stop conflicting services or change ports in docker-compose.yml -docker-compose down -# Edit docker-compose.yml to use different ports -docker-compose up -d +```bash +python manage.py runserver ``` -#### 3. Database Connection Issues -**Issue**: `django.db.utils.OperationalError: could not connect to server` -**Solution**: -```bash -# Ensure database service is running -docker-compose ps +SQLite is used by default for development (no additional setup required). -# Check database logs -docker-compose logs db +--- -# Restart database service -docker-compose restart db +## πŸ—„οΈ Database Overview -# Wait for database to be ready, then run migrations -sleep 10 -docker-compose exec web python manage.py migrate -``` +### Core Models -#### 4. Redis Connection Issues -**Issue**: `redis.exceptions.ConnectionError` in Docker -**Solution**: -```bash -# Check Redis service status -docker-compose ps redis +* User +* Location +* HealthFacility +* AuditTrail -# Restart Redis service -docker-compose restart redis +### Patient Models -# Check Redis logs -docker-compose logs redis -``` +* Patient +* PatientVisit +* PatientMedicalHistory -#### 5. Permission Issues -**Issue**: `Permission denied` errors in Docker containers -**Solution**: -```bash -# Fix file permissions -sudo chown -R $USER:$USER . +### Healthcare Models -# Rebuild containers -docker-compose down -docker-compose build --no-cache -docker-compose up -d -``` +* HealthWorkerProfile +* ProfessionalQualification +* WorkSchedule -#### 6. Memory Issues -**Issue**: Docker containers running out of memory -**Solution**: -```bash -# Check Docker resource usage -docker stats +### Records Models -# Increase Docker memory limit in Docker Desktop settings -# Or add memory limits to docker-compose.yml -``` +* HealthRecord +* VitalSigns +* Medication +* LaboratoryTest -#### 7. Volume Mount Issues -**Issue**: Changes not reflecting in containers -**Solution**: -```bash -# Restart services to pick up volume changes -docker-compose restart web +--- -# Or rebuild if needed -docker-compose down -docker-compose up -d --build -``` +## πŸ”§ Configuration -### Docker Commands Reference +### Environment Variables ```bash -# Start all services -docker-compose up -d - -# Stop all services -docker-compose down - -# View logs -docker-compose logs web -docker-compose logs db -docker-compose logs redis - -# Execute commands in containers -docker-compose exec web python manage.py migrate -docker-compose exec web python manage.py createsuperuser -docker-compose exec web python manage.py shell +SECRET_KEY=your-secret-key +DEBUG=True +ALLOWED_HOSTS=localhost,127.0.0.1 -# Check service status -docker-compose ps +DB_ENGINE=django.db.backends.postgresql +DB_NAME=opencare_africa +DB_USER=opencare_user +DB_PASSWORD=opencare_password +DB_HOST=localhost +DB_PORT=5432 -# Rebuild specific service -docker-compose build web -docker-compose up -d web +REDIS_HOST=localhost +REDIS_PORT=6379 -# Clean up everything -docker-compose down -v -docker system prune -f +JWT_ACCESS_TOKEN_LIFETIME=5 +JWT_REFRESH_TOKEN_LIFETIME=1 ``` -### Common Issues +--- -#### 1. Python Version Compatibility -**Issue**: `ModuleNotFoundError` or package installation failures -**Solution**: Ensure you're using Python 3.11+ and have created a virtual environment -```bash -python3 --version # Should be 3.11+ -python3 -m venv venv -source venv/bin/activate -``` +## πŸ§ͺ Testing -#### 2. Database Migration Errors -**Issue**: `django.db.utils.OperationalError` or migration failures -**Solution**: Ensure the database is properly configured and migrations are up to date ```bash -python manage.py showmigrations -python manage.py migrate +python manage.py test +coverage run --source='.' manage.py test +coverage report ``` -#### 3. Missing Dependencies -**Issue**: `ModuleNotFoundError` for specific packages -**Solution**: Reinstall dependencies and ensure all requirements are met -```bash -pip install --upgrade pip -pip install -r requirements.txt -``` +--- -#### 4. Port Already in Use -**Issue**: `Address already in use` error when starting the server -**Solution**: Use a different port or kill the existing process -```bash -python manage.py runserver 8001 -# OR -pkill -f "python manage.py runserver" -``` +## πŸš€ Deployment -#### 5. Static Files Warning -**Issue**: `staticfiles.W004` warning about missing static directory -**Solution**: Create the static directory (this is normal for development) -```bash -mkdir -p static -``` +### Production Checklist -#### 6. Redis Connection Errors -**Issue**: `redis.exceptions.ConnectionError: Error 111 connecting to localhost:6379` -**Solution**: Redis is not required for basic development. The health check has been configured to skip Redis checks in development mode. If you need Redis for production features, install and start it: -```bash -# Ubuntu/Debian -sudo apt install redis-server -sudo systemctl start redis-server +* Set `DEBUG=False` +* Configure production database +* Enable SSL/TLS +* Configure static files +* Set up monitoring +* Configure backups -# macOS (with Homebrew) -brew install redis -brew services start redis -``` +--- -#### 7. Environment Variables -**Issue**: Configuration errors or missing environment variables -**Solution**: Ensure `.env` file exists and contains required variables -```bash -cp env.example .env -# Edit .env if needed for your environment -``` +## πŸ”’ Security Features -### Development Tips +* JWT authentication +* Role-based access control +* Audit logging +* Input validation +* CORS configuration +* Rate limiting -1. **Use the development settings**: The project uses `config.settings.development` by default -2. **Check logs**: Look at the console output for detailed error messages -3. **Database**: SQLite is used by default for development (no setup required) -4. **API Testing**: Use the built-in API documentation at `/api/docs/` -5. **Admin Interface**: Access at `/admin/` after creating a superuser +--- -### Getting Help +## 🀝 Contributing -- **Documentation**: Check the `/docs/` directory -- **Issues**: Report bugs via GitHub Issues -- **Discussions**: Use GitHub Discussions for questions -- **Email**: Contact the development team +1. Fork the repository +2. Create a feature branch +3. Make changes +4. Add tests +5. Submit a pull request -## πŸ—ΊοΈ Roadmap +--- -### Phase 1 (Current) -- βœ… Core backend infrastructure -- βœ… Patient management system -- βœ… Health worker management -- βœ… Facility management -- βœ… Basic API endpoints +## πŸ“„ License -### Phase 2 (Next) -- πŸ”„ Advanced analytics dashboard -- πŸ”„ Mobile API optimization -- πŸ”„ Integration with external systems -- πŸ”„ Advanced reporting features +MIT License -### Phase 3 (Future) -- πŸ“‹ AI-powered health insights -- πŸ“‹ Telemedicine integration -- πŸ“‹ Advanced data visualization -- πŸ“‹ Multi-language support +--- ## πŸ™ Acknowledgments -- Django community for the excellent framework -- Healthcare professionals for domain expertise -- Open source contributors for various packages -- African healthcare workers for inspiration +* Django community +* Healthcare professionals +* Open-source contributors --- -**OpenCare-Africa** - Empowering healthcare in Africa through technology. +**OpenCare-Africa** β€” Empowering healthcare in Africa through technology.