┌─────────────────┐
│  Business Logic │
└────────┬────────┘
         │ uses
         ▼
┌─────────────────┐
│    Interface    │  ← Defined in specs
└────────┬────────┘
         │ implemented by
    ┌────┴────┐
    ▼         ▼
┌───────┐ ┌───────┐
│ Cloud │ │ Local │
│Adapter│ │Adapter│
└───────┘ └───────┘

MessageQueue:
  - publish(topic: string, message: Message): Promise<void>
  - subscribe(topic: string, handler: MessageHandler): Subscription
  - acknowledge(messageId: string): Promise<void>

ObjectStorage:
  - upload(bucket: string, key: string, data: Buffer): Promise<string>
  - download(bucket: string, key: string): Promise<Buffer>
  - delete(bucket: string, key: string): Promise<void>
  - getSignedUrl(bucket: string, key: string, expiry: number): Promise<string>
  - list(bucket: string, prefix?: string): Promise<ObjectMetadata[]>

Database:
  - query(sql: string, params: any[]): Promise<Result>
  - transaction(fn: (tx: Transaction) => Promise<T>): Promise<T>
  - healthCheck(): Promise<boolean>

DocumentStore:
  - get(collection: string, id: string): Promise<Document | null>
  - put(collection: string, id: string, document: Document): Promise<void>
  - delete(collection: string, id: string): Promise<void>
  - query(collection: string, filter: Filter): Promise<Document[]>

NotificationService:
  - sendEmail(to: string[], subject: string, body: string): Promise<void>
  - sendSms(to: string, message: string): Promise<void>
  - publishEvent(topic: string, event: Event): Promise<void>

AuthService:
  - validateToken(token: string): Promise<TokenPayload>
  - getUserInfo(userId: string): Promise<UserInfo>
  - hasPermission(userId: string, permission: string): Promise<boolean>

SecretsManager:
  - getSecret(name: string): Promise<string>
  - setSecret(name: string, value: string): Promise<void>

SearchService:
  - index(collection: string, id: string, document: Document): Promise<void>
  - search(collection: string, query: SearchQuery): Promise<SearchResult>
  - delete(collection: string, id: string): Promise<void>

CacheService:
  - get(key: string): Promise<T | null>
  - set(key: string, value: T, ttl?: number): Promise<void>
  - delete(key: string): Promise<void>
  - exists(key: string): Promise<boolean>

## External Service: {Service Name}

### Purpose
{What this service does}

### Cloud Implementation
| Aspect | Value |
|--------|-------|
| **Provider** | {AWS/Azure/GCP} |
| **Service** | {Service name} |
| **Configuration** | {Key config} |

### Local Implementation
| Aspect | Value |
|--------|-------|
| **Alternative** | {Local service} |
| **Docker Image** | {image:tag} |
| **Port** | {port} |
| **Configuration** | {Key config} |

### Interface Contract
See: [{interface-name}](../interfaces/{interface-name}.md)

### Adapter Selection
| Environment | Adapter | Connection |
|-------------|---------|------------|
| Production | {CloudAdapter} | {connection string} |
| Local (LOCAL_RUN=true) | {LocalAdapter} | localhost:{port} |

### Data Consistency
- Schema: {Same/Compatible/Mapped}
- Message Format: {JSON/Protobuf/etc}
- Serialization: {Same across adapters}

version: '3.8'

services:
  # Message Queue
  rabbitmq:
    image: rabbitmq:3-management
    ports:
      - "5672:5672"   # AMQP
      - "15672:15672" # Management UI
    environment:
      RABBITMQ_DEFAULT_USER: local
      RABBITMQ_DEFAULT_PASS: local

  # Object Storage
  minio:
    image: minio/minio
    ports:
      - "9000:9000"
      - "9001:9001"
    command: server /data --console-address ":9001"
    environment:
      MINIO_ROOT_USER: minioadmin
      MINIO_ROOT_PASSWORD: minioadmin

  # Database
  postgres:
    image: postgres:15
    ports:
      - "5432:5432"
    environment:
      POSTGRES_USER: local
      POSTGRES_PASSWORD: local
      POSTGRES_DB: app

  # Cache
  redis:
    image: redis:7
    ports:
      - "6379:6379"

  # Email Testing
  mailhog:
    image: mailhog/mailhog
    ports:
      - "1025:1025"  # SMTP
      - "8025:8025"  # Web UI

  # Identity (if needed)
  keycloak:
    image: quay.io/keycloak/keycloak
    ports:
      - "8080:8080"
    environment:
      KEYCLOAK_ADMIN: admin
      KEYCLOAK_ADMIN_PASSWORD: admin
    command: start-dev

LOCAL_RUN=true   # Use local adapters
LOCAL_RUN=false  # Use cloud adapters (default)