In this repository there is the backend infrastructure powering the Mosquito Alert citizen science platform. It manages data collection, validation, and dissemination for mosquito surveillance reports submitted through mobile applications.
Live Server: https://api.mosquitoalert.com/v1/ | https://webserver.mosquitoalert.com
Project Website: https://mosquitoalert.com
- Mosquito Alert
Mosquito Alert harnesses the power of citizen scientists and modern technology to investigate the spread of mosquito species, particularly tiger mosquitoes, across different regions. This Django-based server application:
- Receives and processes mosquito sighting reports from mobile apps
- Manages photo validation and expert classification workflows
- Provides RESTful APIs for mobile applications
- Handles geospatial data processing with PostGIS
- Supports multi-language localization
- Implements robust authentication and authorization
- Generates statistical reports and visualizations
- RESTful API: Comprehensive API built with Django REST Framework
- Geospatial Support: PostGIS integration for geographic data processing
- Expert Validation: Workflow system for report validation and scoring
- Multi-language: Internationalization support for multiple languages
- Push Notifications: FCM integration for mobile notifications
- Image Processing: Automated image handling and validation
- Authentication: JWT-based authentication with Django Simple JWT
- API Documentation: Auto-generated OpenAPI/Swagger documentation with drf-spectacular
- Admin Interface: Enhanced Django admin with custom filters and views
- Asynchronous Tasks: Celery integration for background processing
- Docker and Docker Compose
-
Clone the repository
git clone https://github.com/Mosquito-Alert/mosquito_alert.git cd mosquito_alert -
Build and start containers
make start
This will:
- Build the Docker images
- Start PostgreSQL with PostGIS
- Start the Django application on port 8000
- Run database migrations
-
Create a superuser (optional)
make shell python3 manage.py createsuperuser
The project uses Django settings modules:
config.settings.prod- Production settingsconfig.settings.local- Development settingsconfig.settings.local_ssl- Development with SSL
Environment variables can be set for:
- Database connection
- Secret keys
- Email configuration
- Storage backends
Important: Some API endpoints require attaching pictures in the request body. This can be sensitive for web servers like nginx (but not Apache2), as they have default file upload size limits.
If you're deploying behind nginx, you must increase the maximum allowed body size to 25M to handle image uploads properly:
server {
[...]
client_max_body_size 25M;
}Without this configuration, image upload requests will fail with 413 Request Entity Too Large errors.
# Start all services
make start
# View logs
make logs
# Stop services
make stop
# Restart services
make restartAccess the application:
The Makefile provides convenient commands for development:
| Command | Description |
|---|---|
make start |
Create and start all containers |
make stop |
Stop all containers |
make restart |
Restart all services |
make down |
Stop and remove containers |
make logs |
Show container logs (follow mode) |
make shell |
Open bash shell in Django container |
make psql |
Start PostgreSQL command-line client |
make ps |
List running containers |
make db_restore file=<path> |
Restore database from backup |
make clean_data |
Remove all data volumes |
To run with SSL in development:
SSL=1 make startThe API uses drf-spectacular for automatic OpenAPI schema generation:
- ReDoc: http://localhost:8000/api/v1/
- OpenAPI Schema: http://localhost:8000/api/v1/openapi.yml
We provide official SDKs for multiple programming languages to make integration easier:
| Language | Repository | Description |
|---|---|---|
| 🐍 Python | mosquito-alert-python-sdk | Python client for Mosquito Alert API |
| 📘 TypeScript | mosquito-alert-typescript-sdk | TypeScript/JavaScript SDK |
| 🎯 Dart | mosquito-alert-dart-sdk | Dart SDK for Flutter applications |
| 📊 R | mosquito-alert-R-sdk | R package for data analysis |
These SDKs provide type-safe interfaces, authentication handling, and convenient methods for interacting with the Mosquito Alert API.
The project uses pytest for testing with Django integration.
# Using Docker
docker compose -f docker-compose-local.yml run --rm django pytest
# Or with the shell
make shell
pytest
# Run with coverage
pytest --cov=. --cov-report=html
# Run specific test file
pytest api/tests/test_views.py
# Run specific test
pytest api/tests/test_views.py::TestReportViewSet::test_create_reportTests are configured in pytest.ini:
- Uses
config.settings.localfor testing - Database reuse enabled (
--reuse-db) - Integration tests with Tavern
We welcome contributions to the Mosquito Alert project! Here's how you can help:
-
Fork the repository
git fork https://github.com/Mosquito-Alert/mosquito_alert.git
-
Create a feature branch
git checkout -b feature/amazing-feature
-
Make your changes
- Write clean, documented code
- Add tests for new features
- Update documentation as needed
-
Run tests
pytest
-
Commit your changes
git commit -m "Add amazing feature" -
Push to your fork
git push origin feature/amazing-feature
-
Open a Pull Request
- Provide a clear description of changes
- Reference any related issues
- Ensure all tests pass
- Use GitHub Issues to report bugs
- Include detailed reproduction steps
- Provide system information and logs
- Tag issues appropriately (bug, enhancement, question)
- Discuss major changes by opening an issue first
- Keep pull requests focused on single features/fixes
- Update tests and documentation
- Follow the existing code style
- Be responsive to feedback during code review
This project is licensed under the GNU General Public License v3.0 - see the LICENSE.md file for details.
Mosquito Alert is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
Mosquito Alert Team
- Website: https://mosquitoalert.com
- Email: it@mosquitoalert.com
- GitHub: @Mosquito-Alert
This project is part of a citizen science initiative to monitor and study mosquito populations. Special thanks to all contributors and citizen scientists who make this project possible.
Related Projects:
- 🌍 Map: map
- 💻 Frontend: mosquito_alert_frontend
- 📱 Mobile App: mosquito_alert_mobile_app