# eat2020/geoloc architecture

> Architecture diagram of the GitHub repository eat2020/geoloc, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/eat2020/geoloc
- Repository: https://github.com/eat2020/geoloc

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients
    subgraph "Clients" 
        direction TB
        Client["REST Client\n(cURL, Web/Mobile)"]:::client
        Typeform["Typeform Webhook"]:::client
    end

    %% Edge / Ingress
    subgraph "Ingress Layer"
        direction TB
        APIGW["API Gateway\n(AWS)"]:::edge
        CloudRun["Cloud Run Ingress\n(GCP)"]:::edge
    end

    %% Serverless Container
    subgraph "Serverless Container\n(FastAPI ASGI)" 
        direction TB
        Lambda["Lambda Function\n(ASGI Handler)"]:::compute
        MainApp["ASGI App\n(app/main.py)"]:::compute
    end

    %% FastAPI Application
    subgraph "FastAPI Application" 
        direction TB
        %% Routers
        subgraph "API Routers"
            direction TB
            AddressRouter["Match Router\n(/api/v1/match)\napp/api/routes/address_router.py"]:::router
            WebhookRouter["Webhook Router\n(/api/v1/webhooks/typeform)\napp/api/routes/webhook_router.py"]:::router
        end

        CoreConfig["Config Module\n(app/core/config.py)"]:::core
        Models["Pydantic Models\n(app/models/location.py)"]:::model

        subgraph "Service Layer"
            direction TB
            GeocodingService["GeocodingService\n(app/services/geocoding_service.py)"]:::service
            LocationService["LocationService\n(app/services/location_service.py)"]:::service
            NotificationService["NotificationService\n(app/services/notification_service.py)"]:::service
        end
    end

    %% Data Sources
    subgraph "Data Sources" 
        direction TB
        CSV["locations.csv\n(Sample)"]:::datastore
        Sheets["Google Sheets API"]:::external
        Postgres["Postgres DB"]:::datastore
    end

    %% External Services
    subgraph "External Services"
        direction TB
        HERE["HERE Geocoding API"]:::external
        SendGrid["SendGrid API"]:::external
        Mailgun["Mailgun API"]:::external
        WebhookOut["Admin Webhook Endpoint"]:::external
    end

    %% Deployment Files
    subgraph "Deployment Artifacts"
        direction TB
        Dockerfile["Dockerfile"]:::artifact
        LambdaHandler["lambda_handler.py"]:::artifact
        Requirements["requirements.txt"]:::artifact
    end

    %% Tests
    subgraph "Tests"
        direction TB
        Conftest["tests/conftest.py"]:::test
        TestAPI["tests/test_api.py"]:::test
    end

    %% Flows
    Client -->|HTTP| APIGW
    Typeform -->|Webhook| APIGW
    APIGW --> Lambda
    CloudRun --> Lambda

    Lambda --> MainApp
    MainApp --> AddressRouter
    MainApp --> WebhookRouter
    MainApp --> CoreConfig
    MainApp --> Models

    AddressRouter --> GeocodingService
    AddressRouter --> LocationService
    AddressRouter --> NotificationService

    WebhookRouter --> GeocodingService
    WebhookRouter --> LocationService
    WebhookRouter --> NotificationService

    GeocodingService --> HERE
    LocationService --> CSV
    LocationService --> Sheets
    LocationService --> Postgres
    NotificationService --> SendGrid
    NotificationService --> Mailgun
    NotificationService --> WebhookOut

    %% Click Events
    click Dockerfile "https://github.com/eat2020/geoloc/tree/main/Dockerfile"
    click LambdaHandler "https://github.com/eat2020/geoloc/blob/main/lambda_handler.py"
    click Requirements "https://github.com/eat2020/geoloc/blob/main/requirements.txt"
    click MainApp "https://github.com/eat2020/geoloc/blob/main/app/main.py"
    click AddressRouter "https://github.com/eat2020/geoloc/blob/main/app/api/routes/address_router.py"
    click WebhookRouter "https://github.com/eat2020/geoloc/blob/main/app/api/routes/webhook_router.py"
    click CoreConfig "https://github.com/eat2020/geoloc/blob/main/app/core/config.py"
    click Models "https://github.com/eat2020/geoloc/blob/main/app/models/location.py"
    click GeocodingService "https://github.com/eat2020/geoloc/blob/main/app/services/geocoding_service.py"
    click LocationService "https://github.com/eat2020/geoloc/blob/main/app/services/location_service.py"
    click NotificationService "https://github.com/eat2020/geoloc/blob/main/app/services/notification_service.py"
    click Conftest "https://github.com/eat2020/geoloc/blob/main/tests/conftest.py"
    click TestAPI "https://github.com/eat2020/geoloc/blob/main/tests/test_api.py"

    %% Styles
    classDef client fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef edge fill:#AED6F1,stroke:#333,stroke-width:1px
    classDef compute fill:#D6EAF8,stroke:#333,stroke-width:1px
    classDef router fill:#AED6F1,stroke:#333,stroke-width:1px
    classDef core fill:#A9DFBF,stroke:#333,stroke-width:1px
    classDef model fill:#A9DFBF,stroke:#333,stroke-width:1px
    classDef service fill:#F9E79F,stroke:#333,stroke-width:1px
    classDef datastore fill:#ABEBC6,stroke:#333,stroke-width:1px
    classDef external fill:#F5B7B1,stroke:#333,stroke-width:1px
    classDef artifact fill:#E8DAEF,stroke:#333,stroke-width:1px
    classDef test fill:#FADBD8,stroke:#333,stroke-width:1px
```
