# Module: Services/TileService

## Purpose
Orchestrates tile downloading and persistence. Bridges the downloader (Google Maps) with the tile repository (PostgreSQL), handling cache checks, entity creation, and metadata mapping.

## Public Interface

### TileService (implements ITileService)
- `DownloadAndStoreTilesAsync(double lat, double lon, double sizeMeters, int zoomLevel, CancellationToken) → Task<List<TileMetadata>>`:
  1. Queries existing tiles in the region from the repository (filtered to current year's version)
  2. Calls `GoogleMapsDownloaderV2.GetTilesWithMetadataAsync` with existing tiles to skip
  3. Creates `TileEntity` for each newly downloaded tile and inserts via repository (upsert)
  4. Returns combined list of existing + new tile metadata
- `GetTileAsync(Guid id) → Task<TileMetadata?>`: single tile lookup
- `GetTilesByRegionAsync(double lat, double lon, double sizeMeters, int zoomLevel) → Task<IEnumerable<TileMetadata>>`: query tiles in a region

## Internal Logic
- Version is `DateTime.UtcNow.Year` — tiles are considered fresh for the current calendar year
- `MapToMetadata(TileEntity) → TileMetadata`: entity-to-DTO mapping (static helper)
- Tile size hardcoded to 256 pixels, image type "jpg"
- `MapsVersion` formatted as `"downloaded_{date}"`

## Dependencies
- `GoogleMapsDownloaderV2` (concrete class, not interface)
- `ITileRepository`
- `SatelliteProvider.Common.DTO` — GeoPoint, TileMetadata
- `SatelliteProvider.DataAccess.Models` — TileEntity

## Consumers
- `RegionService.ProcessRegionAsync` — downloads and retrieves tiles for a region

## Data Models
Transforms between `TileEntity` (persistence) and `TileMetadata` (DTO).

## Configuration
None directly; relies on `GoogleMapsDownloaderV2`'s configuration.

## External Integrations
Indirect: Google Maps (via downloader), PostgreSQL (via repository).

## Security
None.

## Tests
No dedicated tests.