Location Service

Location Service Guide

Architecture Overview

apps/location/
├── domain/                          # Pure domain layer
│   ├── entities/                    # NormalizedSite
│   ├── value_objects/               # Coordinates
│   ├── enums/                       # StoreCategory, PickupCategory
│   └── exceptions/                  # LocationNotFoundError
│
├── application/
│   ├── nearby/
│   │   ├── dto/                     # LocationEntryDTO, SuggestEntryDTO, LocationDetailDTO
│   │   ├── ports/                   # LocationReader (ABC)
│   │   ├── queries/                 # GetNearbyCentersQuery, SearchByKeywordQuery, etc.
│   │   └── services/               # CategoryClassifierService, LocationEntryBuilder, ZoomPolicyService
│   └── ports/                       # KakaoLocalClientPort (ABC)
│
├── infrastructure/
│   ├── integrations/kakao/          # KakaoLocalHttpClient
│   ├── persistence_postgres/        # SqlaLocationReader
│   └── observability/               # OpenTelemetry
│
├── presentation/http/
│   ├── controllers/                 # location.py (endpoints)
│   ├── schemas/                     # LocationEntry, SuggestEntry, LocationDetail
│   └── errors/                      # Exception handlers
│
└── setup/
    ├── config.py                    # Settings (pydantic-settings)
    ├── dependencies.py              # FastAPI DI wiring
    └── database.py                  # SQLAlchemy async session

API Endpoints

Key Patterns

1. Hybrid Search Flow (SearchByKeywordQuery)

User Query → Kakao keyword search → Extract coordinates
                                        ↓
                                  DB spatial query (earth_distance/Haversine)
                                        ↓
                                  Merge DB + Kakao results
                                        ↓
                                  Deduplicate (50m threshold)
                                        ↓
                                  Return unified LocationEntryDTO[]

2. Category Classification

CategoryClassifierService.classify(site, metadata) analyzes:

• positn_intdc_cn (introduction text)
• positn_nm (name)
• metadata.clctItemCn (collection items)

Returns: (StoreCategory, list[PickupCategory])

Priority order: REFILL_ZERO > CAFE_BAKERY > VEGAN_DINING > UPCYCLE_RECYCLE > BOOK_WORKSHOP > MARKET_MART > LODGING > PUBLIC_DROPBOX > GENERAL

3. Distance Calculation Fallback

try:
    PostGIS earth_distance (accurate, requires extension)
except DBAPIError:
    Haversine formula (fallback, pure SQL math)

4. Kakao API Integration

• Port: KakaoLocalClientPort (application/ports/)
• Adapter: KakaoLocalHttpClient (infrastructure/integrations/kakao/)
• Singleton via get_kakao_client() in dependencies.py
• Graceful degradation: returns None if LOCATION_KAKAO_REST_API_KEY not set

5. DTO ↔ Schema Mapping

Application layer returns DTOs (dataclasses), presentation layer maps to Pydantic schemas:

Query.execute() → LocationEntryDTO (application layer)
Controller       → LocationEntry (presentation schema, Pydantic)

Environment Variables

Domain Enums

StoreCategory

refill_zero, cafe_bakery, vegan_dining, upcycle_recycle, book_workshop, market_mart, lodging, public_dropbox, general

PickupCategory

clear_pet, can, paper, glass, plastic, vinyl, styrofoam, clothing, electronics, fluorescent, battery, medicine, cooking_oil, general

Testing

pytest apps/location/tests/ -v

Test structure:

• test_domain.py — Entities, Value Objects, Enums (no mocks)
• test_services.py — CategoryClassifier, LocationEntryBuilder, ZoomPolicy
• test_queries.py — GetNearbyCenters, SearchByKeyword, Suggest, CenterDetail (mocked ports)
• test_controllers.py — HTTP parameter validation, endpoint routing

Frontend Integration

Frontend uses:

• VITE_KAKAO_MAP_API_KEY — Kakao Maps JS SDK (client-side, different from backend key)
• VITE_API_BASE_URL — Backend API base URL
• API client: src/api/services/map/map.service.ts
• Types: src/api/services/map/map.type.ts

Common Issues

1. Kakao features disabled: Check LOCATION_KAKAO_REST_API_KEY is set
2. earth_distance not available: Falls back to Haversine (no PostGIS extension)
3. Negative IDs in search results: Kakao-only results use negative IDs (-1, -2, ...)
4. Silent category fallback: Unknown items default to GENERAL

Converted and distributed by TomeVault — claim your Tome and manage your conversions.