How eat2020/geoloc works
Project type and purpose
• This is a specialized micro-service built on FastAPI. Its sole responsibility is to take driver-applicant addresses, geocode them with the HERE API, compute the nearest delivery hub (from a CSV, Google Sheet, or Postgres data source), and send notifications via email or webhook.
• It’s designed to run serverless (AWS Lambda + API Gateway or GCP Cloud Run) but also works locally via uvicorn.
File structure
• Top-level:
• Dockerfile, lambda_handler.py, requirements.txt → container & deployment
• app/ → main application code
• tests/ → unit/integration tests
• Under app/:
• api/routes/ → FastAPI routers (address match, webhook)
• core/ → environment config, Pydantic settings
• models/ → Pydantic DTOs for request/response schemas
• services/ → business logic (geocoding, location lookup, notifications)
• utils/ → shared helpers (if any)
• main.py → ASGI app instantiation
• External config through .env, .env.example
README insights
• Describes external integrations: HERE API, SendGrid, Mailgun, Typeform webhooks
• Data‐source is pluggable: csv, Google Sheets, Postgres
• Supports both single and batch matching
• Deployable as Lambda container or Cloud Run service
a. Main components
1. Clients
– REST clients (cURL, web/mobile apps)
– Typeform (webhook source)
2. Edge/API layer
– API Gateway (AWS) or Cloud Run ingress
– Lambda function (container) running the FastAPI ASGI app
3. FastAPI application (inside container)
– Router: /api/v1/match (single & batch)
– Router: /api/v1/webhooks/typeform
– Core config module
– Models (Pydantic schemas)
– Service layer
• GeocodingService → calls HERE API
• LocationService → reads from CSV / Google Sheets / Postgres
• NotificationService → sends email (SendGrid/Mailgun) or outgoing webhook
4. External dependencies
– HERE Geocoding REST API
– Google Sheets API (when configured)
– Postgres database (if configured)
– SendGrid / Mailgun APIs
– Outgoing webhook endpoint (admin system)
5. Data storage
– locations.csv (in-container sample)
– Optional Postgres instance
b. Relationships & data flows
• Client → API Gateway (or Cloud Run) → Lambda/ASGI
• FastAPI request hits the relevant router → validated by Pydantic models
• GeocodingService.fetchCoordinates() → HERE API → returns lat/lng
• LocationService.loadHubs() → CSV/Sheets/Postgres → returns list of hubs
• Internal compute: nearest hub via Haversine
• NotificationService.send() → sends confirmation to applicant & alert to admin
• Response returned to client
c. Architectural patterns & principles
– Layered architecture: routers → services → external APIs
– “API first” – clear separation of request handling and business logic
– Pluggable data sources via a factory or config-based branching
– Dependency injection via FastAPI for services & config
– Serverless-friendly container image
d. Key technologies/frameworks
– FastAPI, Uvicorn ASGI
– Pydantic for models & settings
– HERE REST API
– Haversine or geopy library for distance calc
– SendGrid, Mailgun, generic webhook
– AWS Lambda + API Gateway, or GCP Cloud Run
– pytest + httpx.AsyncClient for tests