# Architecture Comparison: Current vs Target

## Current Architecture (Monolithic)

```
ai_menu_translator/
├── app/
│   ├── main.py                          ⚠️ Needs update
│   │
│   ├── api/
│   │   ├── routes/
│   │   │   ├── translation.py           ❌ DELETE (move to services/translation/)
│   │   │   ├── wine_matcher.py          ❌ DELETE (move to services/wine_pairing/)
│   │   │   ├── menu_extraction.py       ❌ DELETE (move to services/menu_extraction/)
│   │   │   └── health.py                ⚠️ MOVE to services/health/
│   │   │
│   │   ├── config/
│   │   │   ├── settings.py              ❌ DELETE (replace with shared/config/)
│   │   │   └── logging_config.py        ⚠️ MOVE to shared/config/
│   │   │
│   │   ├── core/
│   │   │   ├── exceptions.py            ❌ DELETE (replace with shared/exceptions/)
│   │   │   ├── constants.py             ❌ DELETE (move VERSION to config)
│   │   │   └── cache.py                 ⚠️ CHECK if used (possibly DELETE)
│   │   │
│   │   ├── models/
│   │   │   ├── requests.py              ❌ DELETE (split to service-specific)
│   │   │   ├── responses.py             ❌ DELETE (split to service-specific)
│   │   │   ├── menu_dto.py              ❌ DELETE (move to services/menu_extraction/)
│   │   │   └── menu_schema.py           ❌ DELETE (move to services/menu_extraction/)
│   │   │
│   │   ├── services/
│   │   │   ├── openai_service.py        ❌ DELETE (replace with shared/clients/)
│   │   │   ├── translation_service.py   ❌ DELETE (move to services/translation/)
│   │   │   ├── wine_pairing_service.py  ❌ DELETE (move to services/wine_pairing/)
│   │   │   ├── menu_extractor_service.py❌ DELETE (move to services/menu_extraction/)
│   │   │   └── allergen_service.py      ❌ DELETE (move to services/translation/dependencies/)
│   │   │
│   │   ├── inference/
│   │   │   └── menu_openai_client.py    ❌ DELETE (replace with unified client)
│   │   │
│   │   └── utils/
│   │       ├── metrics.py               ⚠️ MOVE to shared/utils/
│   │       ├── retry.py                 ⚠️ MOVE to shared/utils/
│   │       ├── text_processing.py       ⚠️ MOVE to shared/utils/
│   │       ├── response_utils.py        ⚠️ MOVE to shared/utils/
│   │       └── version.py               ⚠️ CHECK if needed
│   │
│   └── config/
│       └── config.yaml                  ⚠️ UPDATE to services.yaml
│
└── other_project/                       ❌ DELETE (already integrated)
```

---

## Target Architecture (Service-Oriented)

```
ai_menu_translator/
├── app/
│   ├── main.py                          ✅ Updated entry point
│   │
│   ├── shared/                          ✅ NEW - Shared utilities
│   │   ├── __init__.py
│   │   │
│   │   ├── middleware/                  ✅ NEW - Centralized middleware
│   │   │   ├── __init__.py
│   │   │   ├── auth.py                  # Bearer token authentication
│   │   │   ├── error_handler.py         # Unified error handling
│   │   │   ├── logging.py               # Request/response logging
│   │   │   └── rate_limiter.py          # Rate limiting (future)
│   │   │
│   │   ├── clients/                     ✅ NEW - External clients
│   │   │   ├── __init__.py
│   │   │   └── openai_client.py         # Unified OpenAI client
│   │   │
│   │   ├── exceptions/                  ✅ NEW - Exception hierarchy
│   │   │   ├── __init__.py
│   │   │   ├── base.py                  # Base exception classes
│   │   │   └── http.py                  # HTTP exception mapping
│   │   │
│   │   ├── utils/                       ✅ NEW - Shared utilities
│   │   │   ├── __init__.py
│   │   │   ├── metrics.py               # Moved from app/utils/
│   │   │   ├── retry.py                 # Moved from app/utils/
│   │   │   ├── text_processing.py       # Moved from app/utils/
│   │   │   └── validation.py            # New
│   │   │
│   │   └── config/                      ✅ NEW - Global config
│   │       ├── __init__.py
│   │       ├── base.py                  # Base config classes
│   │       ├── loader.py                # YAML config loader
│   │       └── logging_config.py        # Moved from app/config/
│   │
│   └── services/                        ✅ NEW - Service-oriented
│       ├── __init__.py
│       │
│       ├── translation/                 ✅ Translation Service
│       │   ├── __init__.py
│       │   ├── config.py                # Service config
│       │   ├── service.py               # Business logic (from translation_service.py)
│       │   ├── routes.py                # API routes (from api/routes/translation.py)
│       │   ├── dependencies.py          # Allergen service
│       │   └── models/
│       │       ├── __init__.py
│       │       ├── requests.py          # TranslationRequest, BatchTranslationRequest
│       │       └── responses.py         # All translation responses
│       │
│       ├── wine_pairing/                ✅ Wine Pairing Service
│       │   ├── __init__.py
│       │   ├── config.py                # Service config
│       │   ├── service.py               # Business logic (from wine_pairing_service.py)
│       │   ├── routes.py                # API routes (from api/routes/wine_matcher.py)
│       │   └── models/
│       │       ├── __init__.py
│       │       ├── requests.py          # WinePairingRequest, Food, Wine models
│       │       └── responses.py         # WinePairingResponse
│       │
│       ├── menu_extraction/             ✅ Menu Extraction Service
│       │   ├── __init__.py
│       │   ├── config.py                # Service config
│       │   ├── service.py               # Business logic (from menu_extractor_service.py)
│       │   ├── routes.py                # API routes (from api/routes/menu_extraction.py)
│       │   └── models/
│       │       ├── __init__.py
│       │       ├── requests.py          # Request models
│       │       ├── responses.py         # MenuExtractionResponse
│       │       ├── dto.py               # MenuItem, MenuCategory (from menu_dto.py)
│       │       └── schemas.py           # MENU_JSON_SCHEMA (from menu_schema.py)
│       │
│       └── health/                      ✅ Health Check Service
│           ├── __init__.py
│           └── routes.py                # Health endpoints (from api/routes/health.py)
│
└── config/
    └── services.yaml                    ✅ NEW - Unified service configuration
```

---

## Key Changes Summary

### ✅ NEW Components (To Create)

1. **Shared Infrastructure**
   - `shared/middleware/auth.py` - Centralized authentication
   - `shared/middleware/error_handler.py` - Unified error handling
   - `shared/clients/openai_client.py` - Single OpenAI client
   - `shared/exceptions/base.py` - Exception hierarchy
   - `shared/config/loader.py` - Configuration loader

2. **Service Structure**
   - `services/translation/` - Complete translation service
   - `services/wine_pairing/` - Complete wine pairing service
   - `services/menu_extraction/` - Complete menu extraction service
   - `services/health/` - Health check service

3. **Configuration**
   - `config/services.yaml` - New unified config with per-service settings

### ⚠️ Files to MOVE/REFACTOR

1. **Utilities** (Move to `shared/utils/`)
   - `app/utils/metrics.py`
   - `app/utils/retry.py`
   - `app/utils/text_processing.py`
   - `app/utils/response_utils.py`

2. **Configuration** (Refactor)
   - `app/config/logging_config.py` → `shared/config/logging_config.py`
   - `config/config.yaml` → `config/services.yaml` (restructured)

### ❌ Files to DELETE (After Migration)

1. **Old Services** (Replace with new structure)
   ```
   app/services/openai_service.py
   app/services/translation_service.py
   app/services/wine_pairing_service.py
   app/services/menu_extractor_service.py
   app/services/allergen_service.py
   ```

2. **Old Routes** (Move to services)
   ```
   app/api/routes/translation.py
   app/api/routes/wine_matcher.py
   app/api/routes/menu_extraction.py
   ```

3. **Old Models** (Split to services)
   ```
   app/models/requests.py
   app/models/responses.py
   app/models/menu_dto.py
   app/models/menu_schema.py
   ```

4. **Old Infrastructure** (Replace with shared)
   ```
   app/inference/menu_openai_client.py
   app/core/exceptions.py
   app/config/settings.py
   ```

5. **Directories to Remove**
   ```
   app/api/                    # Completely replaced
   app/models/                 # Split into services
   app/inference/              # Replaced by shared/clients/
   app/core/                   # Mostly replaced
   other_project/              # Already integrated, no longer needed
   ```

---

## Migration Approach

### Phase 1: Build New (Parallel)
✅ Create all `shared/` components
✅ Create all `services/` structure
✅ Keep old code running

### Phase 2: Test New (Side by Side)
✅ Test each service independently
✅ Compare with old responses
✅ Verify backward compatibility

### Phase 3: Switch Over
✅ Update `main.py` to use new services
✅ Remove old imports
✅ Monitor production

### Phase 4: Cleanup
❌ Delete old files
❌ Remove unused code
✅ Update documentation

---

## Service Ownership Matrix

| Service | Config Key | API Key Env | Bearer Token Env | Routes |
|---------|-----------|-------------|------------------|--------|
| Translation | `services.translation` | `OPENAI_API_KEY_TRANSLATION` | `TRANSLATION_SERVICE_KEY` | `/translate-menu-item`<br>`/translate-menu-items` |
| Wine Pairing | `services.wine_pairing` | `OPENAI_API_KEY_WINE` | `WINE_SERVICE_KEY` | `/wine-matcher` |
| Menu Extraction | `services.menu_extraction` | `OPENAI_API_KEY_MENU` | `MENU_EXTRACTION_SERVICE_KEY` | `/menu/extract` |
| Health | `services.health` | N/A | None (public) | `/health` |

---

## Benefits Comparison

| Aspect | Current (Monolithic) | Target (Service-Oriented) |
|--------|---------------------|---------------------------|
| **Services** | Mixed together | Clear separation |
| **Configuration** | Single global config | Per-service config |
| **API Keys** | Shared OpenAI key | Per-service keys |
| **Authentication** | Duplicated in routes | Centralized middleware |
| **Error Handling** | Inconsistent | Unified format |
| **Scalability** | All or nothing | Scale per service |
| **Testing** | Hard to isolate | Easy to test independently |
| **Development** | Sequential changes | Parallel development |
| **Deployment** | Single deployment | Service-by-service |
| **Monitoring** | Mixed metrics | Per-service metrics |

---

## Next Steps

1. **Review** this plan and `refactor_instructions.md`
2. **Create** `shared/` infrastructure
3. **Migrate** one service at a time
4. **Test** thoroughly at each step
5. **Deploy** with confidence
6. **Cleanup** old code

Remember: **DO NOT CHANGE INPUT/OUTPUT FORMATS** - Maintain 100% backward compatibility!