SamoluDavidD/CivicTrack-Liberia

National Reporting Platform -- Liberia # CivicTrack Liberia **Multi-Institution National Civic Operations Platform** CivicTrack Liberia lets citizens report public-service and infrastructure issues — power cuts, damaged roads, fires, flooding, water/sewer faults, garbage, health hazards, security concerns, city services, and disasters — and routes each report automatically to the government institution responsible for the chosen category. Each institution operates an isolated dashboard; overall and super admins retain national visibility. This document is the entry point for the codebase. It covers what the system does, how it's built, how to run it locally, how each role experiences the UI, and the full HTTP API surface. --- ## Table of contents 1. System purpose 2. Tech stack 3. Architecture overview 4. Repository layout 5. Local setup 6. Daily run 7. User roles & permissions 8. Report lifecycle 9. Category → Institution routing 10. Smart category validation 11. Server-side institution isolation 12. Audit log 13. Data model 14. REST API reference 15. Frontend navigation by role 16. Citizen chatbot widget 17. Demo accounts 18. Deployment notes 19. Troubleshooting 20. Roadmap --- ## 1. System purpose Citizens identify a problem (e.g. a transformer fault) and submit a single report with a category, a description, optional photos/voice notes, and optional GPS location. The platform: - Validates the category against the description (keyword-based mismatch warning). - Auto-routes the report to the institution that owns that category — citizens never pick an institution. - Notifies the institution admin, who validates the report, then assigns a field officer. - Tracks the report through `submitted → validated → assigned → in_progress → resolved → closed`, with every transition written to a status log and audit log. - Surfaces national analytics (institution rankings, category distribution, geographic spread) for overall/super admins. The architectural principle is **CATEGORY → INSTITUTION routing** …