Draft: feat: Admin Notification API for Camp Volunteers

Overview:

Implements a broadcast notification endpoint that allows admins to send bulk email and/or push notifications to all volunteers currently signed up for the active medical camp. This is needed to enable real-time camp communication without manual outreach. What does this MR do and why? Adds POST /api/v1/admin/notifications/broadcast — an admin-only endpoint that accepts a title, message, and channel toggles (send_email, send_push), filters only actively signed-up volunteers for the current camp, and dispatches notifications asynchronously via FastAPI BackgroundTasks to avoid API timeouts. Changes Made

Added POST /api/v1/medical-camps/broadcast route in app/api/v1/routes/medical_camp_routes.py Added process_broadcast function in app/services/notification_service.py Integrated existing mailing system for email delivery Integrated Firebase Admin SDK push notifications via stored fcm_token on user model Added get_current_camp service to identify the active camp Added integration tests in tests/test_api/test_broadcast.py Added schema tests in tests/schemas/test_medical_camp_schema.py Technical Details

Architecture decisions:

Used FastAPI BackgroundTasks for async bulk dispatch — endpoint returns 202 Accepted immediately while notifications process in the background Filtering logic queries CampVisit where signup=True, camp_role=volunteer, and camp_id matches the current active camp Channel toggles (send_email, send_push) are evaluated inside the background task so skipped channels incur zero overhead

Issue related : #111 (closed)

Data flow:

Admin sends broadcast request → RBAC check (admin only) Current active camp is fetched via get_current_camp Signed-up volunteers are queried from CampVisit process_broadcast is added to BackgroundTasks and the endpoint returns 202 immediately Background task iterates volunteers, dispatching email and/or push based on toggle flags

Type of Change

✨ New feature (non-breaking change that adds functionality) 🧪 Test update

Expected response: 202 Accepted How to Validate Locally

Start the server and ensure an active medical camp exists in the DB Create volunteer users and sign them up for the current camp via CampVisit Hit the broadcast endpoint as an admin with various send_email/send_push combinations Verify 202 is returned immediately and notifications are dispatched in the background Test with a non-admin token — expect 403 Forbidden

Testing Done

Unit tests added/updated API endpoint tests passing

Test Cases Covered:

ScenarioExpected ResultStatusTC-BE-01: Non-admin or unauthenticated request403 Forbidden / 401 Unauthorized✅TC-BE-02: Empty title or message in payload422 Unprocessable Entity✅TC-BE-03: Only signed-up volunteer (A) targeted; non-signed-up volunteer (B) and doctor (C) excludedOnly user A in broadcast loop✅TC-BE-04: Async execution — endpoint returns before background tasks finish202 Accepted returned instantly✅TC-BE-05: send_email=false, send_push=true — mail service skipped, only push invokedPush dispatched, no email call✅

Code Quality Checklist

Code Standards

Code follows project conventions (naming, structure, formatting) No debug statements or commented-out code left No unused imports, variables, or functions No duplicate code (DRY principle followed) Type hints are properly defined Ruff checks pass

Python & FastAPI Best Practices

Functions follow single-responsibility principle Async/await used correctly Dependency injection used appropriately Pydantic models used for request/response validation Error handling is comprehensive

API Design

RESTful conventions followed Proper HTTP status codes returned (202 Accepted, 403, 422) Input validation implemented via Pydantic Authentication/authorization enforced Role-based access control used (admin only)

Security

No sensitive data logged SQL injection prevention verified (ORM used) Authentication tokens handled securely Security scan passes (bandit -r app/)

Error Handling

404 returned when no active camp is found 202 with empty recipient list handled gracefully

Known Limitations / Technical Debt

Push notifications require fcm_token to be present on the user record; users without a token are silently skipped. A follow-up issue should add token registration and validation. No retry logic for failed notification deliveries — consider a task queue (e.g., Celery + Redis) for production resilience.

Additional Notes

The route path used is /api/v1/medical-camps/broadcast (consistent with existing camp routes) rather than /api/v1/admin/notifications/broadcast from the spec — confirm with the team if a path change is needed. Firebase Admin SDK credentials must be configured via environment variables; .env.example should be updated accordingly.