A civic tech platform that helps residents of Sofia stay informed about infrastructure disruptions. The app automatically aggregates public announcements about water shutoffs, heating maintenance, road repairs, and municipal works, displaying them on an interactive map with push notifications for areas you care about.
This monorepo contains two main components:
Automated crawlers collect notices from public sources (water company, heating provider, municipal sites). AI-powered extraction and multi-service geocoding (Google, OpenStreetMap, Bulgarian Cadastre, GTFS) converts raw text into map-ready GeoJSON. The notification engine matches new disruptions with user-defined interest areas and sends push notifications.
See ingest/ for details.
Next.js application with an interactive Google Maps interface. Users can browse current disruptions, define interest circles with custom radius, and receive push notifications when new issues affect their areas. Installable as a Progressive Web App.
See web/ for details.
- Frontend: Next.js 16, React 19, TypeScript, Google Maps API
- Backend: Node.js, Firebase (Firestore, Auth, Cloud Messaging)
- AI: Google Gemini for address extraction
- Infrastructure: Google Cloud Run, Terraform, Docker, Vercel
- Automation: Playwright for web scraping
- Message Filtering - AI-powered content filtering, address extraction, geocoding, and time-based relevance
- Geocoding System - Multi-service geocoding with Google, OpenStreetMap, Bulgarian Cadastre, and GTFS APIs
- Onboarding Flow - User onboarding state machine for notifications and zone creation
- Ingest Overview - Data collection and processing pipeline architecture
- Message Processing - Filtering, extraction, geocoding, and GeoJSON conversion flow
- Crawlers - Data sources and web scraping implementations
- Notifications - Push notification matching and delivery
- Terraform - Cloud Run deployment and infrastructure
- Web App - PWA installation and browser support
Documentation is written for technical stakeholders, system administrators, and QA personnel who need to understand system behavior and configuration. Focus is on facts and behavior rather than implementation details, with diagrams for complex flows and practical configuration guidance. We keep it short and informative. We avoid excessive explanations of topics that are standard to the industry or easy to understand.
See CONTRIBUTING.md for local development setup instructions, including Firebase and Google Cloud account configuration.