yahaiii/ariran

Nigeria Open Crime Database — multi-source, spatially indexed crime intelligence platform # Nigeria Open Crime Database (ariran) The largest open-source crime dataset in Nigeria — multi-source, spatially indexed, provenance-first. ## Architecture ``` Data Sources → Ingestion Bus → Enrichment (NLP + Geocoding) → PostGIS → API / Exports ``` ## Quick Start ### 1. Prerequisites - Python 3.11+ - Docker + Docker Compose - VSCode (recommended) ### 2. Clone and install ```bash git clone github.com cd ariran cp .env.example .env # fill in DB_PASSWORD, ACLED_API_KEY make install # creates .venv and installs all deps ``` ### 3. Start the database and stack ```bash make dev-up # starts PostGIS + pgAdmin + API via Docker ``` **Or**, run the database and run the API locally: ```bash docker compose up -d db pgadmin # database and admin UI only make init-db # verify connection and seed data make run-api # start the FastAPI app on localhost ``` ### 4. Initialize the database ```bash make init-db # verifies connection and seed data ``` ### 5. Run connectors ```bash make run-nbs # ingest NBS annual crime stats make run-acled # ingest ACLED conflict events (needs API key) ``` ### 6. Run integration tests ```bash make test-integration # run integration tests (live tests skip by default) INTEGRATION_TESTS=1 make test-integration-live ``` Live tests require real credentials and network access. The harness currently includes ACLED, RSS news, Nairaland, and Twitter when `TWITTER_API_KEY` is set. To run live integration tests in GitHub Actions, open the `Integration Tests` workflow and trigger it with `run_live_connectors=true`. Configure repository secrets: `ACLED_EMAIL`, `ACLED_PASSWORD`, `ACLED_API_KEY`, `TWITTER_API_KEY`. ### 7. Access the API Once running, the API is available at: - **API**: localhost - **Interactive Docs**: localhost - **OpenAPI Schema**: http …