Service Architecture Patterns Skill

Overview

The Modular Service Design Pattern provides a structured approach for integrating external services with:

• •Feature isolation in dedicated directories
• •Generic interfaces supporting multiple providers
• •Factory-based instantiation
• •Encapsulation of implementation details

Use this pattern for: Payment processors, CAPTCHA services, Email providers, SMS services, File storage, Analytics services, and any external API integration.

Key Benefits:

• •Extensibility: Easy to add new providers without changing consumers
• •Testability: Mock interfaces instead of concrete implementations
• •Maintainability: Clear separation of concerns and responsibilities
• •Performance: Reusable service instances via closure/singleton patterns
• •Type Safety: Full TypeScript support with proper abstractions

Quick Reference: 7-Step Pattern

1. Feature Isolation

Create isolated service modules under /src/services/[service-name]/:

src/services/[service-name]/
├── index.ts              # Public API exports only
├── [service].ts          # Generic interface
├── factory.ts            # Factory method
├── config.ts             # General configuration interface
└── [provider]/           # Provider-specific implementation

2. Interface Abstraction

Define generic interfaces supporting multiple implementations:

export interface Captcha {
  validate: (token: string) => Promise<void>
}

3. Helper Interfaces

Create supporting types for data structures and configurations:

export interface Config {
  baseUrl: string
  secret: string
  options: RequestOptions
}

4. Concrete Implementation

Implement the generic interface with provider-specific logic:

export class Recaptcha implements Captcha {
  constructor(private config: Config) {}
  async validate(token: string): Promise<void> { /* ... */ }
}

5. Factory Pattern

Provide factory method for service creation:

export const createCaptchaVerifier = (): Captcha => {
  return new Recaptcha(recaptchaConfig)
}

6. Encapsulation Strategy

Export only public API via index.ts:

export type { Captcha } from './captcha'
export { createCaptchaVerifier } from './factory'
// Implementation details NOT exported

7. Usage Pattern

Consume services via factory methods and generic interfaces:

const captchaVerifier = createCaptchaVerifier() // singleton instance
await captchaVerifier.validate(token)

When to Use This Pattern

Use this pattern when:

• •Integrating external third-party services or APIs
• •Multiple provider implementations are needed (or planned)
• •Testing requires mocking external dependencies
• •Service logic should be isolated from business logic
• •Provider may change in the future

Real Examples from Codebase

• •Simple (single provider): /src/services/captcha/ - Google reCAPTCHA
• •Advanced (multiple providers): /src/services/email/ - Ethereal + Resend with registry pattern

Deep Dive References

• •Implementation Guide - Complete 7-step walkthrough with testing strategies
• •Captcha Example - Simple single-provider reference implementation
• •Email Example - Advanced multi-provider with registry and singleton patterns