001 Project structure

app/__init__.py

@@ -0,0 +1 @@
+"""G2S Aggregator application package."""

app/adapters/__init__.py

@@ -0,0 +1 @@
+"""External adapters."""

app/adapters/delivery_providers/__init__.py

@@ -0,0 +1 @@
+"""Delivery provider adapters."""

app/adapters/delivery_providers/base.py

@@ -0,0 +1,16 @@
+"""Base interface for delivery providers."""
+
+from abc import ABC, abstractmethod
+
+from app.schemas.request import DeliveryRequest
+from app.schemas.response import DeliveryPrice
+
+
+class DeliveryProvider(ABC):
+    name: str
+
+    @abstractmethod
+    async def get_price(self, request: DeliveryRequest) -> DeliveryPrice:
+        """Fetch one quote from an external provider."""
+
+        raise NotImplementedError

app/adapters/delivery_providers/cdek/__init__.py

@@ -0,0 +1 @@
+"""CDEK adapter package."""

app/adapters/delivery_providers/cdek/auth.py

@@ -0,0 +1,6 @@
+"""CDEK auth adapter skeleton."""
+
+
+class CDEKAuthClient:
+    async def get_access_token(self) -> str:
+        raise NotImplementedError("CDEK auth implementation is added in task 003.")

app/adapters/delivery_providers/cdek/client.py

@@ -0,0 +1,9 @@
+"""CDEK HTTP client adapter skeleton."""
+
+from app.schemas.request import DeliveryRequest
+
+
+class CDEKClient:
+    async def get_raw_price(self, request: DeliveryRequest) -> dict:
+        _ = request
+        raise NotImplementedError("CDEK client implementation is added in task 003.")

app/adapters/delivery_providers/cdek/mapper.py

@@ -0,0 +1,8 @@
+"""CDEK response mapper skeleton."""
+
+from app.schemas.response import DeliveryPrice
+
+
+def map_cdek_response(payload: dict) -> DeliveryPrice:
+    _ = payload
+    raise NotImplementedError("CDEK mapper implementation is added in task 003.")

app/config.py

@@ -0,0 +1,93 @@
+"""Application configuration split by architecture component."""
+
+import os
+from functools import lru_cache
+
+from pydantic import BaseModel, Field
+from pydantic_settings import (
+    BaseSettings,
+    PydanticBaseSettingsSource,
+    SettingsConfigDict,
+    YamlConfigSettingsSource,
+)
+
+DEFAULT_CONFIG_FILE = "config.yaml"
+CONFIG_FILE_ENV = "G2S_CONFIG_FILE"
+
+
+class ControllerConfig(BaseModel):
+    api_prefix: str = "/api/v1"
+    request_id_header: str = "X-Request-ID"
+
+
+class ServiceConfig(BaseModel):
+    provider_timeout_seconds: float = 10.0
+    max_parallel_providers: int = 8
+
+
+class BusinessLogicConfig(BaseModel):
+    weight_round_scale: int = 2
+
+
+class RepositoryConfig(BaseModel):
+    redis_dsn: str = "redis://localhost:6379/0"
+    price_cache_ttl_seconds: int = 900
+
+
+class AdapterConfig(BaseModel):
+    cdek_base_url: str = "https://api.cdek.ru/v2"
+    cdek_timeout_seconds: float = 10.0
+
+
+class ObservabilityConfig(BaseModel):
+    service_name: str = "g2s-aggregator"
+    otlp_endpoint: str = "http://localhost:4317"
+    log_level: str = "INFO"
+
+
+class AlertsConfig(BaseModel):
+    telegram_enabled: bool = False
+    telegram_bot_token: str | None = None
+    telegram_chat_id: str | None = None
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_prefix="G2S_",
+        env_nested_delimiter="__",
+        extra="ignore",
+    )
+
+    controller: ControllerConfig = Field(default_factory=ControllerConfig)
+    service: ServiceConfig = Field(default_factory=ServiceConfig)
+    business_logic: BusinessLogicConfig = Field(default_factory=BusinessLogicConfig)
+    repository: RepositoryConfig = Field(default_factory=RepositoryConfig)
+    adapter: AdapterConfig = Field(default_factory=AdapterConfig)
+    observability: ObservabilityConfig = Field(default_factory=ObservabilityConfig)
+    alerts: AlertsConfig = Field(default_factory=AlertsConfig)
+
+    @classmethod
+    def settings_customise_sources(
+        cls,
+        settings_cls: type[BaseSettings],
+        init_settings: PydanticBaseSettingsSource,
+        env_settings: PydanticBaseSettingsSource,
+        dotenv_settings: PydanticBaseSettingsSource,
+        file_secret_settings: PydanticBaseSettingsSource,
+    ) -> tuple[PydanticBaseSettingsSource, ...]:
+        yaml_source = YamlConfigSettingsSource(
+            settings_cls,
+            yaml_file=os.getenv(CONFIG_FILE_ENV, DEFAULT_CONFIG_FILE),
+        )
+        return (
+            init_settings,
+            env_settings,
+            dotenv_settings,
+            yaml_source,
+            file_secret_settings,
+        )
+
+
+@lru_cache(maxsize=1)
+def get_settings() -> Settings:
+    return Settings()

app/controllers/__init__.py

@@ -0,0 +1 @@
+"""HTTP layer components."""

app/controllers/http_client.py

@@ -0,0 +1,7 @@
+"""Controller-level HTTP client factory."""
+
+from httpx import AsyncClient
+
+
+def build_controller_http_client(timeout_seconds: float) -> AsyncClient:
+    return AsyncClient(timeout=timeout_seconds)

app/controllers/middleware.py

@@ -0,0 +1,10 @@
+"""HTTP middleware registration."""
+
+from fastapi import FastAPI
+
+
+def install_middleware(app: FastAPI) -> None:
+    """Register middleware components for the API."""
+
+    # Middleware stack is introduced in later tasks.
+    _ = app

app/controllers/v1/__init__.py

@@ -0,0 +1 @@
+"""Versioned API controllers."""

app/controllers/v1/delivery.py

@@ -0,0 +1,5 @@
+"""Delivery API controller skeleton."""
+
+from fastapi import APIRouter
+
+router = APIRouter(prefix="/delivery", tags=["delivery"])

app/domain/__init__.py

@@ -0,0 +1 @@
+"""Pure business logic layer."""

app/domain/quotes.py

@@ -0,0 +1,4 @@
+"""Business rules for delivery quotes.
+
+Rules are implemented in task 002.
+"""

app/main.py

@@ -0,0 +1,21 @@
+"""FastAPI application entrypoint."""
+
+from fastapi import FastAPI
+
+from app.config import Settings, get_settings
+from app.controllers.middleware import install_middleware
+from app.controllers.v1.delivery import router as delivery_router
+
+
+def create_app(settings: Settings | None = None) -> FastAPI:
+    resolved_settings = settings or get_settings()
+
+    application = FastAPI(title="G2S Aggregator", version="0.1.0")
+    application.state.settings = resolved_settings
+
+    install_middleware(application)
+    application.include_router(delivery_router, prefix=resolved_settings.controller.api_prefix)
+    return application
+
+
+app = create_app()

app/repositories/__init__.py

@@ -0,0 +1 @@
+"""Repository layer."""

app/repositories/cache/__init__.py

@@ -0,0 +1 @@
+"""Cache repositories."""

app/repositories/cache/redis_cache.py

@@ -0,0 +1,17 @@
+"""Redis cache repository skeleton."""
+
+from typing import Any
+
+
+class PriceCache:
+    async def get(self, key: str) -> Any | None:
+        _ = key
+        raise NotImplementedError("Redis repository implementation is added in task 004.")
+
+    async def set(self, key: str, value: Any, ttl: int) -> None:
+        _ = (key, value, ttl)
+        raise NotImplementedError("Redis repository implementation is added in task 004.")
+
+    async def invalidate(self, key: str) -> None:
+        _ = key
+        raise NotImplementedError("Redis repository implementation is added in task 004.")

app/schemas/__init__.py

@@ -0,0 +1 @@
+"""Shared API and domain schemas."""

app/schemas/request.py

@@ -0,0 +1,20 @@
+"""Input schemas for price calculation."""
+
+from enum import StrEnum
+
+from pydantic import BaseModel, Field
+
+
+class DeliveryEntity(StrEnum):
+    INDIVIDUAL = "individual"
+    LEGAL = "legal"
+
+
+class DeliveryRequest(BaseModel):
+    entity: DeliveryEntity
+    from_city: str = Field(min_length=1)
+    to_city: str = Field(min_length=1)
+    weight_kg: float = Field(gt=0)
+    length_cm: float = Field(gt=0)
+    width_cm: float = Field(gt=0)
+    height_cm: float = Field(gt=0)

app/schemas/response.py

@@ -0,0 +1,14 @@
+"""Output schemas for aggregated prices."""
+
+from decimal import Decimal
+
+from pydantic import BaseModel, Field
+
+
+class DeliveryPrice(BaseModel):
+    provider: str = Field(min_length=1)
+    service_name: str = Field(min_length=1)
+    price: Decimal = Field(gt=0)
+    currency: str = Field(min_length=3, max_length=3)
+    delivery_days_min: int = Field(ge=0)
+    delivery_days_max: int = Field(ge=0)

app/services/__init__.py

@@ -0,0 +1 @@
+"""Application service layer."""

app/services/aggregator.py

@@ -0,0 +1,10 @@
+"""Aggregator service orchestrator skeleton."""
+
+from app.schemas.request import DeliveryRequest
+from app.schemas.response import DeliveryPrice
+
+
+class AggregatorService:
+    async def get_all_prices(self, request: DeliveryRequest) -> list[DeliveryPrice]:
+        _ = request
+        raise NotImplementedError("Aggregator workflow is implemented in task 005.")