facial_recog_2.py

---
title: Service Architecture Guidelines
description: Strict Serivice Oriented Architecture
globs:
alwaysApply: true
---

# Service-Oriented Architecture (SOA) Guidelines

This project follows a strict Service-Oriented Architecture pattern. All services must adhere to these principles:

## Service Method Design

### Request/Response Pattern

- **All public service methods MUST use a single request object and return a single response object**
- **Avoid multiple parameters** - encapsulate all input data in a request object
- **Use dataclasses** for request/response objects to ensure type safety and clarity

### Examples of Correct Service Methods

\```python
# ✅ CORRECT - Single request/response objects
def detect_faces(self, request: FaceDetectionRequest) -> FaceDetectionResponse:
    # Implementation here
    pass

def display_collage(self, request: DisplayCollageRequest) -> DisplayCollageResponse:
    # Implementation here
    pass
\```

### Examples of Incorrect Service Methods

\```python
# ❌ INCORRECT - Multiple parameters
def detect_faces(self, image_paths: List[str], backend: str = 'opencv') -> FaceDetectionResponse:
    pass

# ❌ INCORRECT - No request/response objects
def display_image(self, image, window_name: str, wait_key: bool) -> bool:
    pass
\```


## Project Structure

- **Services**: Located in [services/](mdc:services/) directory
- **Data Contracts**: Each service should have its data contracts in the same folder as the service
- **Configuration**: Located in [config/](mdc:config/) directory
- **Utilities**: Located in [utils/](mdc:utils/) directory

## Key Principles

1. **Single Responsibility**: Each service has one clear purpose
2. **Service Decoupling**: Services should be completely decoupled from each other
   - Services should NOT reference each other directly
   - Services should NOT import or use contracts from other services
   - Services can only reference utilities (utils) and their own contracts
3. **Dependency Injection**: Use the DI container in [config/container.py](mdc:config/container.py)
4. **Request/Response Contracts**: All service communication uses explicit data contracts
5. **Error Handling**: Response objects should include success status and error messages
6. **Shared Contracts**: Use [services/shared_contracts.py](mdc:services/shared_contracts.py) for data structures shared between services

## Reference Implementation

See [services/face_detection_service.py](mdc:services/face_detection_service.py) and [services/display_service.py](mdc:services/display_service.py) for examples of proper SOA implementation with request/response patterns.