아키텍처 가이드¶

┌─────────────────────────────────────────────────────────────────┐
│                        HTTP Layer                               │
│  ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐   │
│  │     Routes      │ │   Middleware    │ │   Handlers      │   │
│  │                 │ │                 │ │                 │   │
│  │ • /v1/models    │ │ • Logging       │ │ • Streaming     │   │
│  │ • /v1/chat/*    │ │ • Metrics       │ │ • Responses API │   │
│  │ • /v1/responses │ │ • Rate Limit    │ │ • DTOs          │   │
│  │ • /admin/*      │ │ • Auth          │ │ • Error         │   │
│  └─────────────────┘ └─────────────────┘ └─────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
                                   │
                                   ▼
┌─────────────────────────────────────────────────────────────────┐
│                     Services Layer                              │
│  ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐   │
│  │ Backend Service │ │  Model Service  │ │ Proxy Service   │   │
│  │                 │ │                 │ │                 │   │
│  │ • Pool Mgmt     │ │ • Aggregation   │ │ • Routing       │   │
│  │ • Load Balance  │ │ • Caching       │ │ • Streaming     │   │
│  │ • Health Check  │ │ • Discovery     │ │ • Retry Logic   │   │
│  │                 │ │ • Metadata      │ │                 │   │
│  └─────────────────┘ └─────────────────┘ └─────────────────┘   │
│                                                                 │
│  ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐   │
│  │ Health Service  │ │ Service Registry│ │ Deduplication   │   │
│  │                 │ │                 │ │                 │   │
│  │ • Monitoring    │ │ • Lifecycle     │ │ • Cache         │   │
│  │ • Status Track  │ │ • Dependencies  │ │ • Request Hash  │   │
│  │ • Recovery      │ │ • Container     │ │ • TTL Mgmt      │   │
│  └─────────────────┘ └─────────────────┘ └─────────────────┘   │
│                                                                 │
│  ┌─────────────────┐                                            │
│  │  File Service   │  참조: architecture/file-storage.md        │
│  │                 │                                            │
│  │ • Upload/Delete │                                            │
│  │ • Metadata Mgmt │                                            │
│  │ • Persistence   │                                            │
│  └─────────────────┘                                            │
└─────────────────────────────────────────────────────────────────┘
                                   │
                                   ▼
┌─────────────────────────────────────────────────────────────────┐
│                 Infrastructure Layer                            │
│  ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐   │
│  │    Backends     │ │      Cache      │ │     Common      │   │
│  │                 │ │                 │ │                 │   │
│  │ • OpenAI        │ │ • LRU Cache     │ │ • HTTP Client   │   │
│  │ • Anthropic     │ │ • TTL Cache     │ │ • Executor      │   │
│  │ • Gemini        │ │ • Retry Cache   │ │ • Statistics    │   │
│  │ • vLLM          │ │                 │ │ • URL Validator │   │
│  └─────────────────┘ └─────────────────┘ └─────────────────┘   │
│                                                                 │
│  ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐   │
│  │  Configuration  │ │  Backend Pool   │ │  Backend Factory  │ │
│  │                 │ │                 │ │                   │ │
│  │ • File Watcher  │ │ • Pool Mgmt     │ │ • Create Backend  │ │
│  │ • Env Override  │ │ • Connection    │ │ • Type Detection  │ │
│  │ • Validation    │ │ • Pre-warming   │ │ • Config Parsing  │ │
│  └─────────────────┘ └─────────────────┘ └─────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
                                   │
                                   ▼
┌─────────────────────────────────────────────────────────────────┐
│                       Core Layer                                │
│  ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐   │
│  │     Models      │ │     Traits      │ │     Errors      │   │
│  │                 │ │                 │ │                 │   │
│  │ • Backend       │ │ • BackendTrait  │ │ • CoreError     │   │
│  │ • Model         │ │ • ServiceTrait  │ │ • RouterError   │   │
│  │ • Request       │ │ • CacheTrait    │ │ • ErrorSeverity │   │
│  │ • Response      │ │ • HealthTrait   │ │ • ErrorDetail   │   │
│  └─────────────────┘ └─────────────────┘ └─────────────────┘   │
│                                                                 │
│  ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐   │
│  │  Retry Logic    │ │  Configuration  │ │   Container     │   │
│  │                 │ │                 │ │                 │   │
│  │ • Policies      │ │ • Models        │ │ • DI Container  │   │
│  │ • Strategies    │ │ • Validation    │ │ • Service Mgmt  │   │
│  │ • Backoff       │ │ • Defaults      │ │ • Lifecycle     │   │
│  └─────────────────┘ └─────────────────┘ └─────────────────┘   │
│                                                                 │
│  ┌─────────────────┐                                           │
│  │ Circuit Breaker │                                           │
│  │                 │                                           │
│  │ • State Machine │                                           │
│  │ • Failure Track │                                           │
│  │ • Auto Recovery │                                           │
│  └─────────────────┘                                           │
└─────────────────────────────────────────────────────────────────┘

src/http/
├── mod.rs              # HTTP 계층 내보내기
├── routes.rs           # 라우트 정의 및 핸들러
├── dto.rs              # 요청/응답 DTO
├── handlers/           # 요청 핸들러
│   ├── mod.rs
│   └── responses.rs    # Responses API 핸들러
├── middleware/         # HTTP 미들웨어 컴포넌트
│   ├── mod.rs
│   ├── auth.rs         # API 키 인증 미들웨어
│   ├── admin_auth.rs   # Admin API 인증 미들웨어
│   ├── files_auth.rs   # Files API 인증 미들웨어
│   ├── admin_audit.rs  # Admin 작업 감사 로깅
│   ├── logging.rs      # 요청/응답 로깅
│   ├── metrics.rs      # 메트릭 수집
│   ├── metrics_auth.rs # 메트릭 엔드포인트 인증
│   ├── model_extractor.rs # 요청에서 모델 추출
│   ├── prometheus.rs   # Prometheus 메트릭 통합
│   ├── rate_limit.rs   # 속도 제한 미들웨어 (레거시)
│   └── rate_limit_v2/  # 향상된 속도 제한 (모듈화)
│       ├── mod.rs      # 모듈 내보내기
│       ├── middleware.rs # 속도 제한 미들웨어
│       ├── store.rs    # 속도 제한 저장소 및 추적
│       └── token_bucket.rs # 토큰 버킷 알고리즘
└── streaming/          # SSE 스트리밍 핸들러
    ├── mod.rs
    └── handler.rs      # 스트리밍 응답 처리

src/services/
├── mod.rs              # 서비스 레지스트리 및 관리
├── backend_service.rs  # 백엔드 관리 서비스
├── model_service.rs    # 모델 집계 서비스
├── proxy_service.rs    # 요청 프록시 및 라우팅
├── health_service.rs   # 헬스 모니터링 서비스
├── deduplication.rs    # 요청 중복 제거 서비스
├── responses/          # Responses API 지원
│   ├── mod.rs
│   ├── converter.rs    # 응답 형식 변환
│   ├── session.rs      # 세션 관리
│   └── streaming.rs    # 스트리밍 응답 처리
└── streaming/          # 스트리밍 유틸리티
    ├── mod.rs
    ├── parser.rs       # 스트림 파싱 로직
    └── transformer.rs  # 스트림 변환 (OpenAI/Anthropic)

src/infrastructure/
├── mod.rs              # 인프라 내보내기 및 유틸리티
├── backends/           # 백엔드 구현
│   ├── mod.rs
│   ├── anthropic/      # 네이티브 Anthropic Claude 백엔드
│   │   ├── mod.rs      # 백엔드 구현 및 요청 변환
│   │   └── stream.rs   # SSE 스트림 변환기 (Anthropic → OpenAI)
│   ├── gemini/         # 네이티브 Google Gemini 백엔드
│   │   ├── mod.rs      # TTFB 최적화가 있는 백엔드 구현
│   │   └── stream.rs   # SSE 스트림 변환기 (Gemini → OpenAI)
│   ├── openai/         # OpenAI 호환 백엔드
│   │   ├── mod.rs
│   │   ├── backend.rs  # OpenAI 백엔드 구현
│   │   └── models/     # OpenAI 특화 모델 정의
│   ├── factory/        # 백엔드 팩토리 패턴
│   │   ├── mod.rs
│   │   └── backend_factory.rs  # 설정에서 백엔드 생성
│   ├── pool/           # 백엔드 풀링 및 관리
│   │   ├── mod.rs
│   │   ├── backend_pool.rs     # 연결 풀 관리
│   │   └── backend_manager.rs  # 백엔드 라이프사이클 관리
│   ├── generic/        # 제네릭 백엔드 구현
│   │   └── mod.rs
│   └── vllm.rs         # vLLM 백엔드 구현
├── common/             # 공유 인프라 유틸리티
│   ├── mod.rs
│   ├── executor.rs     # 재시도/메트릭이 있는 요청 실행
│   ├── headers.rs      # HTTP 헤더 유틸리티
│   ├── http_client.rs  # 풀링이 있는 HTTP 클라이언트 팩토리
│   ├── statistics.rs   # 백엔드 통계 수집
│   └── url_validator.rs # URL 검증 및 보안
├── cache/              # 캐싱 구현
│   ├── mod.rs
│   ├── lru_cache.rs    # LRU 캐시 구현
│   └── retry_cache.rs  # 재시도 인식 캐시
├── config/             # 설정 관리
│   ├── mod.rs
│   ├── loader.rs       # 설정 로딩
│   ├── validator.rs    # 설정 검증
│   ├── timeout_validator.rs # 타임아웃 설정 검증
│   ├── watcher.rs      # 핫 리로드를 위한 파일 감시
│   ├── migrator.rs     # 설정 마이그레이션 오케스트레이터
│   ├── migration.rs    # 마이그레이션 타입 및 트레이트
│   ├── migrations.rs   # 특정 마이그레이션 구현
│   ├── fixer.rs        # 자동 수정 로직
│   ├── backup.rs       # 백업 관리
│   └── secrets.rs      # 시크릿/API 키 관리
└── lock_optimization.rs # 락 및 동시성 최적화

src/core/
├── mod.rs              # 코어 내보내기 및 유틸리티
├── models/             # 도메인 모델
│   ├── mod.rs
│   ├── backend.rs      # 백엔드 도메인 모델
│   ├── model.rs        # LLM 모델 표현
│   ├── request.rs      # 요청 모델
│   └── responses.rs    # 응답 모델 (Responses API)
├── traits.rs           # 핵심 트레이트 및 인터페이스
├── errors.rs           # 오류 타입 및 처리
├── container.rs        # 의존성 주입 컨테이너
├── async_utils.rs      # 비동기 유틸리티 함수
├── duration_utils.rs   # Duration 파싱 유틸리티
├── streaming/          # 스트리밍 모델
│   ├── mod.rs
│   └── models.rs       # 스트리밍 특화 모델
├── retry/              # 재시도 메커니즘
│   ├── mod.rs
│   ├── policy.rs       # 재시도 정책
│   └── strategy.rs     # 재시도 전략
├── circuit_breaker/    # 서킷 브레이커 패턴
│   ├── mod.rs          # 모듈 내보내기
│   ├── config.rs       # 설정 모델
│   ├── state.rs        # 상태 머신 및 브레이커 로직
│   ├── error.rs        # 서킷 브레이커 오류
│   ├── metrics.rs      # Prometheus 메트릭
│   └── tests.rs        # 단위 테스트
├── files/              # 파일 처리 유틸리티
│   ├── mod.rs          # 모듈 내보내기
│   ├── resolver.rs     # 채팅 요청에서 파일 참조 해석
│   ├── transformer.rs  # 파일 콘텐츠가 있는 메시지 변환
│   └── transformer_utils.rs # 변환 유틸리티 함수
└── config/             # 설정 모델
    ├── mod.rs
    ├── models/            # 설정 데이터 모델 (모듈화 구조)
    │   ├── mod.rs         # 하위 호환성을 위한 재내보내기
    │   ├── config.rs      # 메인 Config 구조체, ServerConfig, BackendConfig
    │   ├── backend_type.rs # BackendType 열거형 정의
    │   ├── model_metadata.rs # ModelMetadata, PricingInfo, CapabilityInfo
    │   ├── global_prompts.rs # GlobalPrompts 설정
    │   ├── samples.rs     # 샘플 생성 설정
    │   ├── validation.rs  # 설정 검증 로직
    │   └── error.rs       # 설정 특화 오류
    ├── timeout_models.rs # 타임아웃 설정 모델
    ├── cached_timeout.rs # 캐시된 타임아웃 해석
    ├── optimized_retry.rs # 최적화된 재시도 설정
    ├── metrics.rs      # 메트릭 설정
    └── rate_limit.rs   # 속도 제한 설정

pub struct BackendPool {
    backends: Arc<RwLock<Vec<Backend>>>,
    load_balancer: LoadBalancingStrategy,
    health_checker: Option<Arc<HealthChecker>>,
}

impl BackendPool {
    // 헬스 인식 라운드 로빈 로드 밸런싱
    pub async fn select_backend(&self) -> Option<Backend> { /* ... */ }

    // 모델 가용성으로 백엔드 필터링
    pub async fn backends_for_model(&self, model: &str) -> Vec<Backend> { /* ... */ }
}

pub struct HealthChecker {
    backends: Arc<RwLock<Vec<Backend>>>,
    config: HealthConfig,
    status_map: Arc<RwLock<HashMap<String, HealthStatus>>>,
}

pub struct HealthConfig {
    pub interval: Duration,
    pub timeout: Duration,
    pub unhealthy_threshold: u32,  // 비정상으로 표시하기 전 실패 횟수
    pub healthy_threshold: u32,    // 정상으로 표시하기 전 성공 횟수
}

src/models/
├── mod.rs             # 하위 호환성을 위한 재내보내기
├── types.rs           # Model, AggregatedModel, ModelList 타입
├── metrics.rs         # ModelMetrics 추적
├── cache.rs           # ModelCache 구현
├── config.rs          # ModelAggregationConfig
├── fetcher.rs         # 백엔드에서 모델 가져오기
├── handlers.rs        # /v1/models 엔드포인트용 HTTP 핸들러
├── utils.rs           # 유틸리티 함수 (normalize_model_id 등)
└── aggregation/       # 핵심 집계 로직
    ├── mod.rs         # ModelAggregationService 구현
    └── tests.rs       # 단위 테스트

pub struct ModelAggregationService {
    cache: Arc<RwLock<ModelCache>>,
    config: ModelAggregationConfig,
    backends: Arc<BackendPool>,
}

impl ModelAggregationService {
    // 모든 정상 백엔드에서 모델 집계
    pub async fn get_aggregated_models(&self) -> Result<ModelList, Error> { /* ... */ }

    // 설정의 메타데이터로 모델 보강
    pub fn merge_config_metadata(&self, models: &mut Vec<Model>) { /* ... */ }

    // TTL 및 중복 제거가 있는 캐시
    pub async fn refresh_models(&self) -> Result<(), Error> { /* ... */ }
}

src/proxy/
├── mod.rs             # 하위 호환성을 위한 재내보내기
├── backend.rs         # 백엔드 선택 및 라우팅 로직
├── request.rs         # 재시도 로직이 있는 요청 실행
├── files.rs           # 요청에서 파일 참조 해석
├── image_gen.rs       # 이미지 생성 처리 (DALL-E, Gemini, GPT Image)
├── image_edit.rs      # 이미지 편집 지원 (/v1/images/edits)
├── image_utils.rs     # 이미지 처리 유틸리티 (멀티파트, 검증)
├── handlers.rs        # 프록시 엔드포인트용 HTTP 핸들러
├── utils.rs           # 유틸리티 함수 (오류 응답 등)
└── tests.rs           # 단위 테스트

pub struct EnhancedRetryHandler {
    config: RetryConfig,
    dedup_cache: Arc<Mutex<HashMap<String, CachedResponse>>>,
    dedup_ttl: Duration,
}

pub struct RetryConfig {
    pub max_attempts: u32,
    pub base_delay: Duration,
    pub max_delay: Duration,
    pub exponential_backoff: bool,
    pub jitter: bool,
}

pub struct CircuitBreaker {
    states: Arc<DashMap<String, BackendCircuitState>>,
    config: CircuitBreakerConfig,
    metrics: Option<CircuitBreakerMetrics>,
}

pub struct CircuitBreakerConfig {
    pub enabled: bool,
    pub failure_threshold: u32,           // 열리기 전 실패 횟수 (기본값: 5)
    pub failure_rate_threshold: f64,      // 실패율 임계값 (기본값: 0.5)
    pub minimum_requests: u32,            // 비율 계산 전 최소 요청 수
    pub timeout_seconds: u64,             // 서킷이 열린 상태로 유지되는 시간 (기본값: 60초)
    pub half_open_max_requests: u32,      // half-open 상태에서 최대 요청 수
    pub half_open_success_threshold: u32, // 닫히는 데 필요한 성공 횟수
}

pub enum CircuitState {
    Closed,    // 정상 작동 - 요청 통과
    Open,      // 빠른 실패 - 요청 즉시 거부
    HalfOpen,  // 복구 테스트 - 제한된 요청 허용
}

pub struct Container {
    services: Arc<RwLock<HashMap<TypeId, Box<dyn Any + Send + Sync>>>>,
    singletons: Arc<RwLock<HashMap<TypeId, Arc<dyn Any + Send + Sync>>>>,
}

impl Container {
    // 싱글톤 서비스 등록
    pub async fn register_singleton<T>(&self, instance: Arc<T>) -> CoreResult<()>
    where T: 'static + Send + Sync { /* ... */ }

    // 서비스 의존성 해석
    pub async fn resolve<T>(&self) -> CoreResult<Arc<T>>
    where T: 'static + Send + Sync { /* ... */ }
}

// V1ToV2Migration 구현
fn migrate(&self, config: &mut Value) -> Result<(), MigrationError> {
    // 단일 backend_url을 backends 배열로 변환
    if let Some(backend_url) = config.get("backend_url") {
        let mut backends = Vec::new();
        let mut backend = Map::new();
        backend.insert("url".to_string(), backend_url.clone());

        // 모델을 백엔드로 이동
        if let Some(model) = config.get("model") {
            backend.insert("models".to_string(),
                Value::Sequence(vec![model.clone()]));
        }

        backends.push(Value::Mapping(backend));
        config["backends"] = Value::Sequence(backends);

        // 이전 필드 제거
        config.remove("backend_url");
        config.remove("model");
    }
    Ok(())
}

// main.rs에서
async fn setup_services(config: Config) -> Result<ServiceRegistry, Error> {
    let container = Arc::new(Container::new());

    // 인프라 서비스 등록
    container.register_singleton(Arc::new(
        HttpClient::new(&config.http_client)?
    )).await?;

    container.register_singleton(Arc::new(
        BackendManager::new(&config.backends)?
    )).await?;

    // 핵심 서비스 등록
    container.register_singleton(Arc::new(
        BackendServiceImpl::new(container.clone())
    )).await?;

    container.register_singleton(Arc::new(
        ModelServiceImpl::new(container.clone())
    )).await?;

    // 서비스 레지스트리 생성
    let registry = ServiceRegistry::new(container);
    registry.initialize().await?;

    Ok(registry)
}

pub struct ProxyServiceImpl {
    backend_service: Arc<dyn BackendService>,
    model_service: Arc<dyn ModelService>,
    retry_handler: Arc<dyn RetryHandler>,
    http_client: Arc<HttpClient>,
}

impl ProxyServiceImpl {
    pub fn new(container: Arc<Container>) -> CoreResult<Self> {
        Ok(Self {
            backend_service: container.resolve()?,
            model_service: container.resolve()?,
            retry_handler: container.resolve()?,
            http_client: container.resolve()?,
        })
    }
}

┌─────────────────────────────────────────────────────────────────┐
│                   OpenAI 형식 요청                                │
│  POST /v1/chat/completions                                       │
│  { "model": "claude-haiku-4-5", "messages": [...] }             │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│              요청 변환 레이어                                     │
│  transform_openai_to_anthropic_request()                        │
│  • 시스템 메시지 추출 → 별도의 `system` 매개변수                   │
│  • image_url 변환 → Anthropic 이미지 형식                        │
│  • max_tokens / max_completion_tokens 매핑                       │
│  • reasoning_effort 변환 → thinking 매개변수                     │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                  Anthropic Messages API                          │
│  POST https://api.anthropic.com/v1/messages                     │
│  Headers: x-api-key, anthropic-version: 2023-06-01              │
│  { "model": "...", "system": "...", "messages": [...] }         │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│              AnthropicStreamTransformer                          │
│  SSE 이벤트 변환 (Anthropic → OpenAI 형식)                        │
│  • message_start → role이 있는 초기 청크                          │
│  • content_block_delta → 콘텐츠 청크                              │
│  • thinking_delta → reasoning_content (확장된 사고)               │
│  • message_delta → finish_reason 매핑                            │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                   OpenAI 형식 응답                                │
│  data: {"choices":[{"delta":{"content":"..."}}]}                │
└─────────────────────────────────────────────────────────────────┘

// OpenAI reasoning_effort → Anthropic thinking
{
  "reasoning_effort": "high"  // OpenAI 형식
}
// 다음으로 변환:
{
  "thinking": {
    "type": "enabled",
    "budget_tokens": 32768   // effort 레벨에서 매핑
  }
}

// src/services/load_balancer.rs에서
pub enum LoadBalancingStrategy {
    RoundRobin,
    WeightedRoundRobin,
    LeastConnections,  // 새 전략
    Random,
}

impl LoadBalancingStrategy {
    pub fn select_backend(&self, backends: &[Backend]) -> Option<&Backend> {
        match self {
            Self::RoundRobin => /* ... */,
            Self::WeightedRoundRobin => /* ... */,
            Self::LeastConnections => self.select_least_connections(backends),
            Self::Random => /* ... */,
        }
    }
}

// 캐시 효율성을 위해 최적화된 데이터 구조
pub struct Backend {
    pub name: String,          // 작은 이름을 위한 인라인 문자열
    pub url: Arc<str>,         // URL을 위한 공유 문자열
    pub weight: u32,           // 컴팩트한 정수
    pub is_healthy: AtomicBool, // 락 프리 헬스 상태
}

// 캐시 친화적 모델 저장소
pub struct ModelCache {
    models: HashMap<String, Arc<ModelInfo>>, // 공유된 모델 정보
    last_updated: AtomicU64,                 // 락 프리 타임스탬프
    ttl: Duration,
}

src/http/middleware/rate_limit_v2/
├── mod.rs              # 공개 API 및 모듈 내보내기
├── middleware.rs       # Axum 미들웨어 통합
├── store.rs            # 속도 제한 저장소 및 클라이언트 추적
└── token_bucket.rs     # 토큰 버킷 알고리즘 구현

rate_limiting:
  enabled: true
  sustained:
    max_requests: 100
    window_seconds: 60
  burst:
    max_requests: 20
    window_seconds: 5
  cleanup_interval_seconds: 300

요청 도착
    ↓
클라이언트 ID 추출 (API 키 또는 IP)
    ↓
지속 제한 확인 (100 req/min)
    ↓ OK
버스트 제한 확인 (20 req/5s)
    ↓ OK
요청 처리

┌─────────────────────────────────────────────────────────────────┐
│                   OpenAI 호환 요청                                │
│  POST /v1/images/generations                                     │
│  { "model": "...", "prompt": "...", "size": "1536x1024" }       │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    모델 라우터 (image_gen.rs)                     │
│  • 모델 타입 감지 (GPT Image, DALL-E, Nano Banana)                │
│  • 적절한 핸들러로 라우팅                                          │
│  • 스트리밍 vs 비스트리밍 처리                                     │
└─────────────────────────────────────────────────────────────────┘
                   │                              │
        ┌──────────┘                              └──────────┐
        ▼                                                     ▼
┌───────────────────────────┐           ┌───────────────────────────┐
│    OpenAI 백엔드           │           │    Gemini 백엔드           │
│    (GPT Image, DALL-E)    │           │    (Nano Banana)           │
│                           │           │                            │
│  • 요청 패스스루          │           │  • Gemini API로 변환       │
│  • SSE 스트리밍 지원      │           │  • size → aspectRatio 매핑  │
│  • output_format 지원     │           │  • imageConfig 생성        │
└───────────────────────────┘           └───────────────────────────┘

{
  "model": "nano-banana",
  "prompt": "고요한 일본 정원",
  "size": "1536x1024",
  "n": 1
}

{
  "contents": [
    {
      "parts": [{"text": "고요한 일본 정원"}]
    }
  ],
  "generationConfig": {
    "imageConfig": {
      "aspectRatio": "3:2",
      "imageSize": "1K"
    }
  }
}

pub fn convert_openai_to_gemini(request: &OpenAIImageRequest)
    -> CoreResult<(String, GeminiImageRequest)>
{
    // 1. 모델 이름 매핑
    let gemini_model = map_model_to_gemini(&request.model);

    // 2. 크기를 종횡비 및 크기 카테고리로 파싱
    let parsed_size = parse_openai_size(&request.size, &request.model)?;

    // 3. imageConfig가 있는 Gemini 요청 빌드
    let gemini_request = GeminiImageRequest {
        contents: vec![GeminiContent { parts: vec![...] }],
        generation_config: Some(GeminiGenerationConfig {
            image_config: Some(GeminiImageConfig {
                aspect_ratio: Some(parsed_size.aspect_ratio.to_gemini_string()),
                image_size: Some(parsed_size.size_category.to_gemini_image_size()),
            }),
        }),
    };

    Ok((gemini_model, gemini_request))
}

┌─────────────┐                ┌─────────────┐                ┌─────────────┐
│   클라이언트 │────stream:true─▶│   라우터    │────stream:true─▶│   OpenAI    │
│             │                │             │                │             │
│             │◀───SSE 이벤트──│  패스스루   │◀───SSE 이벤트──│             │
└─────────────┘                └─────────────┘                └─────────────┘

async fn handle_streaming_image_generation(...) -> Result<Response, StatusCode> {
    // 1. 백엔드 요청에서 stream: true 유지
    // 2. bytes_stream()을 통해 스트리밍 요청 수행
    // 3. tokio 채널을 통해 SSE 이벤트 전달

    let (tx, rx) = tokio::sync::mpsc::unbounded_channel();

    tokio::spawn(async move {
        let mut stream = backend_response.bytes_stream();
        while let Some(chunk) = stream.next().await {
            // SSE 형식 파싱 (event:/data: 라인)
            // 클라이언트에 이벤트 전달
            for line in chunk_str.lines() {
                if let Some(event_type) = line.strip_prefix("event:") { ... }
                if let Some(data) = line.strip_prefix("data:") {
                    let event = Event::default().event(event_type).data(data);
                    tx.send(Ok(event));
                }
            }
        }
    });

    Ok(Sse::new(UnboundedReceiverStream::new(rx)).into_response())
}

image: <file>           # 원본 이미지 (PNG, 필수)
prompt: <string>        # 편집 지침 (필수)
mask: <file>            # 선택적 마스크 이미지 (PNG)
model: <string>         # 모델 이름 (예: "gpt-image-1", "dall-e-2")
n: <integer>            # 이미지 수 (기본값: 1)
size: <string>          # 출력 크기 (예: "1024x1024")
response_format: <string> # "url" 또는 "b64_json"

image: <file>           # 소스 이미지 (PNG, 필수)
model: <string>         # 모델 이름 (기본값: "dall-e-2")
n: <integer>            # 변형 수 (기본값: 1, 최대: 10)
size: <string>          # 출력 크기 ("256x256", "512x512", "1024x1024")
response_format: <string> # "url" 또는 "b64_json"