Add POI feature and imporve the overall backend implementation

services/external/README.md

@@ -42,12 +42,22 @@ The **External Service** integrates real-world data from Spanish sources to enha
 - **Rate Limit Management** - Respect API usage limits
 - **Error Logging** - Detailed error tracking and alerts
 
+### POI Context Detection
+- **OpenStreetMap Integration** - Automatic detection of Points of Interest (POIs) near bakery locations
+- **18+ POI Categories** - Schools, offices, transport hubs, residential areas, commercial zones, and more
+- **Competitive Intelligence** - Identify nearby competing bakeries and complementary businesses
+- **Location-Based Features** - Generate ML features from POI proximity and density
+- **High-Impact Categories** - Automatically identify POI categories most relevant to bakery demand
+- **Caching & Optimization** - PostgreSQL storage with spatial indexing for fast retrieval
+- **Onboarding Integration** - Automatic POI detection during bakery setup
+
 ### Feature Engineering
 - **Weather Impact Scores** - Calculate weather influence on demand
 - **Traffic Influence** - Quantify traffic effect on foot traffic
 - **Holiday Types** - Categorize holidays by demand impact
 - **Season Detection** - Identify seasonal patterns
 - **Weekend vs. Weekday** - Business day classification
+- **POI Features** - Location context features from nearby points of interest
 - **Combined Features** - Multi-factor feature generation
 
 ## Business Value
@@ -89,6 +99,16 @@ The **External Service** integrates real-world data from Spanish sources to enha
 
 ## API Endpoints (Key Routes)
 
+### POI Detection & Context
+- `POST /poi-context/{tenant_id}/detect` - Detect POIs for tenant location (lat, long, force_refresh params)
+- `GET /poi-context/{tenant_id}` - Get cached POI context for tenant
+- `POST /poi-context/{tenant_id}/refresh` - Force refresh POI detection
+- `DELETE /poi-context/{tenant_id}` - Delete POI context for tenant
+- `GET /poi-context/{tenant_id}/feature-importance` - Get POI feature importance summary
+- `GET /poi-context/{tenant_id}/competitor-analysis` - Get competitive analysis
+- `GET /poi-context/health` - Check POI service and Overpass API health
+- `GET /poi-context/cache/stats` - Get POI cache statistics
+
 ### Weather Data (AEMET)
 - `GET /api/v1/external/weather/current` - Current weather for location
 - `GET /api/v1/external/weather/forecast` - 7-day weather forecast
@@ -121,10 +141,47 @@ The **External Service** integrates real-world data from Spanish sources to enha
 - `GET /api/v1/external/health/traffic` - Traffic API status
 - `GET /api/v1/external/metrics` - API usage metrics
 
+### Geocoding (Address Lookup)
+- `GET /api/v1/geocoding/search` - Search addresses with autocomplete
+- `GET /api/v1/geocoding/reverse` - Reverse geocode coordinates to address
+- `GET /api/v1/geocoding/health` - Check geocoding service health
+
 ## Database Schema
 
 ### Main Tables
 
+**tenant_poi_contexts** (POI Data Storage)
+```sql
+CREATE TABLE tenant_poi_contexts (
+    id UUID PRIMARY KEY,
+    tenant_id UUID NOT NULL UNIQUE,                     -- Tenant reference
+    bakery_location JSONB NOT NULL,                     -- {latitude, longitude, address}
+
+    -- POI detection results
+    poi_detection_results JSONB NOT NULL,               -- Full detection results by category
+    total_pois_detected INTEGER DEFAULT 0,
+    relevant_categories TEXT[],                          -- Categories with POIs nearby
+    high_impact_categories TEXT[],                       -- High-relevance categories
+
+    -- ML features for forecasting
+    ml_features JSONB,                                   -- Pre-computed ML features
+
+    -- Competitive analysis
+    competitive_insights JSONB,                          -- Nearby bakeries and competition
+
+    -- Metadata
+    detected_at TIMESTAMP DEFAULT NOW(),
+    last_refreshed_at TIMESTAMP,
+    detection_radius_meters INTEGER DEFAULT 1000,
+    osm_data_timestamp TIMESTAMP,
+
+    created_at TIMESTAMP DEFAULT NOW(),
+    updated_at TIMESTAMP DEFAULT NOW()
+);
+
+CREATE INDEX idx_tenant_poi_tenant ON tenant_poi_contexts(tenant_id);
+```
+
 **weather_data**
 ```sql
 CREATE TABLE weather_data (
@@ -907,17 +964,21 @@ python main.py
 - **AEMET API** - Spanish weather data
 - **Madrid Open Data** - Traffic data
 - **Spanish Government** - Holiday calendar
+- **OpenStreetMap Overpass API** - POI detection data source
+- **Nominatim API** - Geocoding and address lookup
 - **Auth Service** - User authentication
-- **PostgreSQL** - External data storage
+- **PostgreSQL** - External data storage (weather, traffic, holidays, POIs)
 - **Redis** - API response caching
 - **RabbitMQ** - Event publishing
 
 ### Dependents
-- **Forecasting Service** - Uses external features for ML models
-- **AI Insights Service** - Weather/holiday-based recommendations
+- **Forecasting Service** - Uses external features (weather, traffic, holidays, POI features) for ML models
+- **Training Service** - Fetches POI features during model training
+- **AI Insights Service** - Weather/holiday/location-based recommendations
 - **Production Service** - Weather-aware production planning
 - **Notification Service** - Holiday and weather alerts
-- **Frontend Dashboard** - Display weather and holidays
+- **Frontend Dashboard** - Display weather, holidays, and POI detection results
+- **Onboarding Flow** - Automatic POI detection during bakery setup
 
 ## Business Value for VUE Madrid