Local Alternatives

Service Categories & Local Alternatives

1. Message Queues

Interface Pattern:

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

Adapter Selection:

• LOCAL_RUN=true → RabbitMQ adapter (localhost:5672)
• LOCAL_RUN=false → Cloud adapter (SQS/Service Bus/Pub/Sub)

2. Object/Blob Storage

Interface Pattern:

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[]>

Adapter Selection:

• LOCAL_RUN=true → MinIO adapter (localhost:9000)
• LOCAL_RUN=false → Cloud adapter (S3/Blob/GCS)

3. Relational Databases

Interface Pattern:

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

Note: Use same database engine locally - no adapter needed if using standard SQL. Use environment variables for connection strings.

4. NoSQL Databases

Interface Pattern:

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[]>

5. Notification Services

Interface Pattern:

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

Adapter Selection:

• LOCAL_RUN=true → MailHog (email), Console logger (SMS), RabbitMQ (events)
• LOCAL_RUN=false → Cloud services

6. Authentication/Identity

Interface Pattern:

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

Local Simplification: For E2E testing, LOCAL_RUN=true can use a simplified auth that:

• Accepts predefined test tokens
• Returns mock user data
• Bypasses real authentication (see local-setup skill)

7. Secrets Management

Interface Pattern:

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

Adapter Selection:

• LOCAL_RUN=true → Environment variables or .env file
• LOCAL_RUN=false → Cloud secrets manager

8. Serverless Functions / Event Triggers

Adapter Pattern:

• Extract business logic into testable modules
• Thin handler wrapper for cloud-specific triggers
• Local: HTTP endpoint calling same business logic
• Cloud: Lambda/Function handler calling same business logic

9. Search Services

Interface Pattern:

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

10. Caching

Interface Pattern:

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>

Architecture Specification Template

When architects specify services, they MUST include adapter requirements:

## 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}

Docker Compose Template for Local Services

Architects should reference this in .specs/deployment/local-services.md: