estifanosbereket1/mebrat-backend

A FastAPI backend that scrapes a public Telegram channel for Ethiopian Electric Utility (EEU) power outage announcements, filters for Amharic posts, parses structured outage data (date, time, region, locations) out of the free-form Amharic text, and exposes it via a read-only REST API. # Ethiopian Power Outage Tracker -- Backend A FastAPI backend that scrapes a public Telegram channel for Ethiopian Electric Utility (EEU) power outage announcements, filters for Amharic posts, parses structured outage data (date, time, region, locations) out of the free-form Amharic text, and exposes it via a read-only REST API. The parser never guesses: if it can't confidently extract a date, a time block, or at least one location from a post, the post is stored with `parsed_ok = false` and a specific `parse_fail_reason` rather than partial or best-guess data. See Known Limitations for what this means in practice on real data. ## Project layout ``` app/ config.py settings, loaded from .env database.py SQLAlchemy engine/session models.py ORM models (9 tables) schemas.py Pydantic response models main.py FastAPI app routers/ outages.py, locations.py, auth.py, subscriptions.py, devices.py auth/ security.py (hashing, JWT), dependencies.py (get_current_user) notifications/ push_service.py (Firebase Admin), subscription_notifier.py ethiopian_calendar.py Ethiopian Gregorian date conversion, Amharic date formatting language_filter.py Ethiopic-vs-Latin script detection parser/ date/time/location extraction + orchestrator scraper/ telegram_scraper.py, run_scraper.py, scheduler.py scripts/ backfill_reparse.py re-parse already-stored posts after a parser change alembic/ DB migrations tests/ pytest suite (119 tests) ``` ## 1. Prerequisites - Python 3.12 - Docker + Docker Compose (for local Postgres) - A Telegram account, and API credentials from (log in -> "API development tools" -> create an app -> copy the `api_id` and `api_hash`). This is a **user** login via Telethon, not a bot token. ## 2. Setup ```bash python3 -m venv .venv source .venv/bin/activate pip install -r requ …