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 is a pnpm workspace monorepo. Always run pnpm install at the repository root.
The shared package builds automatically via postinstall hook. Dependencies are managed by pnpm with shamefully-hoist=true.
CRITICAL: When modifying shared package schemas, rebuild is required before running code in web/ingest:
- Run
pnpm buildinshared/directory, OR - Run
pnpm installat repository root (triggers postinstall hook)
This monorepo contains three packages:
- shared/ - Shared TypeScript schemas (Zod) used by both web and ingest
- ingest/ - Automated data collection and processing pipeline
- web/ - Next.js web application
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
- Message URLs - Short, shareable URLs for deep-linking to messages
- Geocoding System - Multi-service geocoding with Google, OpenStreetMap, Bulgarian Cadastre, and GTFS APIs
- Onboarding Flow - User onboarding state machine for notifications and zone creation
- Locality Configuration - Environment-based locality configuration for hosting in different cities
- Your Sofia API - Public API contract for the Your Sofia mobile client
- 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.
Choose your setup path based on what you're working on:
- Front-end only (no Java/Docker): Quick Start: Front-End with MSW - Mock Service Worker for UI development
- Full stack (emulators): Quick Start: Firebase Emulators - Local Firebase for backend integration
- Production deployment: Production Setup Guide - Google Cloud configuration
See CONTRIBUTING.md for detailed development guidelines.
